STraTOS 1997 April & May/STraTOS 1 - 1997 April & May.iso/CD01/DOCS/GFABASIC/GFABASIC.TXT

Text File | 1987-04-21 | 207.8 KB | 6,586 lines

August 1991

No part of this publication may be copied ,  transmitted or stored
in  a retrieval system or reproduced in any way including but  not
limited  to photography,  photocopy,  magnetic or other  recording
means,  without prior written permission from the publishers, with
the  exception of material entered and executed for  the  reader's
own use.

This version created for ST FORMAT.

THIS IS NOT PUBLIC DOMAIN. FULL COPYRIGHT REMAINS IN FORCE.


MARCH 1992

Copyright 1991 GFA Data Media (UK) Ltd

Published by:  GFA Data Media (UK) Ltd
               Box 121
               Wokingham
               Berkshire
               RG11 5XT

Special Offer to ST Format Readers

This  document  is  over  129 pages if  printed  on  A4.  We  have
documented  all  GFA-BASIC  commands.  All  commands  are also
contained in the full GFA-BASIC REFERENCE manual which contains
much more information than is contained in this  'brief' document.
Most commands are fully explained with an example program.


You  can obtain the FULL documentation,  normally sold  for  50.00
pounds for only 25.00 pounds (plus 5.00 postage).  All orders must
be returned direct to GFA,  using the special coupon in the  issue
of ST Format that this disk was supplied with.

Also you can obtain the GFA-BASIC Compiler 3.5 and manual for only
20.00  (plus  postage of 5.00).  (normally  30.00).  The  compiler
manual  contains 48 pages.  You will need the compiler to  produce
desk top accessories and link C and assembler code into your  GFA-
BASIC programs.

Or  order both the Interpreter and Compiler for only  45.00  (plus
5.00 postage) which would normally retail for 80.00.


Please  make  Cheques  and  Postal  Orders  payable  to   GFA-DATA
MEDIA (UK) LTD. We also can accept VISA and ACCESS credit cards.




TECHNICAL SUPPORT

Technical  Support is only available to users who  have  purchased
the full GFA-BASIC 3.5 Interpreter.  All technical problems should
be sent to GFA in writing, enclosing a stamped addressed envelope,
and  quoting  their registration card number (supplied  with  each
purchased  product).  Sorry but we are unable to supply  technical
support  to  users  who are unable  to  quote  their  registration
number.

Now to the documentation:

Introduction

Welcome to GFA-BASIC.  With the GFA-BASIC interpreter you now have
the opportunity to explore the Atari ST,  and create  professional
programs.

We  believe that GFA is the best programming  language  available,
not  just for the Atari ST,  but also for the  Amiga,  MS-DOS  and
Windows 3.0/3.1.  When you have quickly mastered GFA-BASIC for the
Atari ST,  you can transport your program to any PC running either
MS-DOS or Windows (and soon OS/2 and Unix!).  This means that  you
will  only  need  to learn one language for  all  these  different
machines and operating systems.

This  manual contains all the GFA-BASIC 3.5  command  descriptions
and syntax. This manual is an edited version of the full reference
manual (which is over 540 pages) and is a reference manual for the
GFA-BASIC  commands  only.  The  full  reference  manual  contains
example  programs for most of the commands and reference  material
for the Atari BIOS, XBIOS and GEMDOS.

This manual is a reference manual for the GFA-BASIC  commands.  It
does  not attempt to teach you to program,  there are other  books
available for this purpose.  Neither does this edited manual  does
not  document  the hardware or operating system  features  of  the
Atari.

This is the GFA-BASIC Interpreter. There are many more products in
the  GFA range to help you develop your programs.  Please  contact
your  distributor or GFA for more information and prices of  these
products.

GFA-BASIC Interpreter Reference Manual (Full version)

This  loose  leaf manual has over 540  pages,  dealing  with  each
command  with  a full description an  example.  The  Atari  system
routines,  GEMDOS, AES, VDI and GDOS are all described. The Line-A
call  is  also described (although Line-A is now  declared  as  un
supported by Atari). Just about every useful table is presented in
this  manual,  including  GFA-BASIC  error  messages,  Bomb  Error
messages,  TOS Error messages, Scan code table, ASCII tables, Fill
and style patterns, and VT-52 control codes.

GFA-BASIC Compiler

The  GFA-BASIC  Compiler will compile your interpreter  code  into
fast stand alone programs. Desk top accessories can also be easily
created.  The  GFA-BASIC Compiler also has options for  optimising
code  for  either  speed or  size.  External  code,  either  C  or
assembler  can  also be linked into your programs using  the  GFA-
BASIC Compiler. The manual (48 pages) fully explains how to create
a desk top accessory with examples. The compiler also supports the
Atari TT, allowing code to be compiled for either ST or TT ram.

GFA-BASIC Software Development Book

This  book  covers  in  depth  structured  programming,  debugging
routines, Line A calls, Assembly routines, AES functions and GDOS.
Special attention is paid to dialog boxes and their creation. This
book  is over 341 pages and is supported by a disk containing  the
many examples of source code discussed within the book.

GFA GEM Utility Pack

THE  GEM GUP is a framework of GFA-BASIC 3 routines that  you  can
merge  into  your own programs.  GUP takes the  responsibility  of
managing  the intricate GEM interface,  leaving the programmer  to
concentrate  on  the  main  program  logic.  The  example  program
supplied demonstrates how easy it is to create alternative  icons,
and  use up to 5 different window types.  The  demonstration  also
shows how to use all the GEM gadgets, including scroll bars, title
bar, info bar, grow box, grab bar etc. GFA GUP is a quick start to
programming GEM.  GUP is supplied with a 60 page manual and  disk,
fully documenting all of the GEM routines.

GFA Assembler

An integrated development tool for the Atari  ST/STE,  comprising
editor,  macro assembler,  linker and debugger. Supports multiple
window,  file compare,  background assembly. Editor checks syntax
of  machine  code on entry,  hence ideal for programmers  new  to
assembly language. Also creates files that can be loaded directly
into GFA-BASIC.

GFA-Basic and Assembler User Book

This  book covers all that you will need to know  in  interfacing
assembler routines into GFA-BASIC on the Atari  ST/STE.  Includes
an introduction into assembly programming,  creation of desk  top
accessories, graphic manipulation. Book (364 pages) plus disk.

GFA G-Shell

Professional  development  shell for  GFA-BASIC  Interpreter  and
Compiler  on the Atari ST/STE and TT.
GFA-GShell allows the programmer to  skip between Interpreter  and
Compiler  and other programs,  such as an assembler  and  resource
editor.   Supports make facility and  on line help files.  If  you
are using GFA-BASIC Interpreter and Compiler professionally,  then
GFA-GShell will improve your productivity.

GFA-DRAFT 3.2

Powerful  and  comprehensive,  yet easy to use CAD  software  for
Atari ST/STE and Atari TT.  Runs in both high and medium  resolu-
tions.  Icon and menu driven commands. There are symbol libraries
for  electrical,  electronic users and architects.  Libraries  of
symbols are also easy to create.

A  program/macro interface (using GFA BASIC) will enable  you  to
create complex forms and repetive patterns.  Exports:  HPGL,  DXF
and  GEM  files.  Will  support almost any model  of  printer  or
plotter.  GFA-Draft  Plus  3.2  also  supports  the  Atari  laser
printer.


These GFA products and others are available from:

GFA Data Media (UK) Ltd
Box 121
Wokingham
Berkshire
UK RG11 5XT

Sales Line Only     Tel: [phone]
                    Fax: [phone]




Using GFA-BASIC for the first time

The GFA-BASIC program disk is not copy protected, so before you do
anything else,  make a copy and store the original disk in a  safe
place.

GFA-BASIC  is started by double clicking on the program file  icon
GFABASIC.PRG.  After  a  short  while the Editor  screen  will  be
displayed,  which is where you can write and debug your  programs.
Lets  now  try entering an example program.  Enter  the  following
program lines, pressing the RETURN key at the end of each line.

DEFFILL 1,2,8
REPEAT
  WHILE MOUSEK=1
    PBOX MOUSEX,MOUSEY,MOUSEX+30,MOUSEY+30
  WEND
UNTIL MOUSEK=2

In the upper right hand corner of the editor screen you will find
the RUN menu item. Click the RUN button or press Shift and F10
keys together and the example program will start. A simple program
showing the use of the mouse. Move the mouse while holding down
the left button. End the program by pressing the right mouse
button. Press the Return key to end the program. The program could
also have been stopped by pressing the CONTROL, SHIFT and
ALTERNATE keys all at the same time. You will now be returned to
the editor.

GFA-BASIC does not need line numbers. It is bad programming
practice to say GOTO 10. If you must use GOTO, then use:

GOTO label
...
label:

GFA-BASIC offers you the chance to create structured programs, and
indented   in  such  a  way  to  enable  easy  documentation   and
understanding of program flow.

How  to proceed from here.  We suggest you first  become  familiar
with  the GFA-BASIC Interpreter's editor.  Then load some  of  the
demonstration  programs from the disk and  run  these.  Experiment
with these programs by changing the values of variables to see the
effect.  The  next step really depends upon the  individual,  your
knowledge  of the Atari,  your knowledge of programming  and  your
program requirements.  What ever your experience or  requirements,
GFA-BASIC  is the best documented programming  language  available
for the Atari ST, and there are several books and development aids
to help you.



The Editor

THE GFA-BASIC Editor has been specially designed for program
development. Syntax errors are recognised as you type the commands
in, and in addition the commands are indented automatically.

Only one instruction per line is allowed, but a comment may be
added to the end of a line by beginning the comment with a ! mark.

Program lines may be up to 255 characters long, but when a line
exceeds 80 characters, the line will scroll.


Cursor Keypad

Left arrow          moves cursor left one character
Right arrow         moves cursor right one character
Up arrow            moves cursor up one line
Down arrow          moves cursor down one line

Insert              Inserts a blank line
ClrHome             moves cursor to top left corner
Ctrl ClrHome        moves cursor to start of program listing

Help                With the help key procedures and functions can
                    be folded and unfolded. Move the cursor to the
                    start of a procedure or function and then
                    press Help. The procedure will the fold down
                    to a single line

Numeric Keypad

Ctrl 4              moves cursor left one character
Ctrl 6              moves cursor right one character
Ctrl 8              moves cursor up one line
Ctrl 2              moves cursor down one line
Ctrl 7              jumps to start of program
Ctrl 1              jump to end of program
Ctrl 9              move one page up
Ctrl 3              move one page down
Ctrl 0              Inserts a line
Ctrl .              deletes a line

The numeric keypad can be swithed to a mode where it is not
required to press the Ctrl key. This mode is toggled on and off by
pressing Ctrl and - on the numeric keypad.

Delete              deletes character at cursor position
Backspace           deletes character to left of cursor
Tab                 moves cursor right eight characters
Ctrl Tab            moves cursor left eight characters
Return              moves cursor to start of next line
Enter               moves cursor to start of next line
Escape              enter Direct Mode

Further editor commands

Ctrl Delete         deletes line which cursor is on
Ctrl U              un-deletes line
Ctrl Y              deletes line which cursor is on
Ctrl N              inserts blank line
Ctrl Q              call Block menu (as F4)
Ctrl B              mark start of block
Ctrl K              mark end of block
Ctrl R              Page up
Ctrl C              Page down
Ctrl E              replace text
Shift Ctrl E        find replace text
Ctrl F              find text
Ctrl left arrow     cursor to start of line
Ctrl right arrow    cursor to end of line
Ctrl up arrow       page up
Ctrl down arrow     page down
Ctrl Clr Home       cursor to start of program
Ctrl P              delete character right of cursor
Ctrl O              undelete text deleted with Ctrl P
Ctrl Z              cursor to end of program
Ctrl Tab            cursor left eight characters
Ctrl G              move to line number display

Editor marks

Ctrl n              where n= 0 to 6 will mark a position
Alt n               will jump to marked position n, except:

Alt 7               cursor to last cursor position before RUN
Alt 8               to start of program
Alt 9               cursor to start of last search
Alt 0               cursor to position of last change

Menu Bar

Atari Logo

This leads to a GEM menu bar:

Save

A file select box will appear, and a program can be saved by
entering a name and selecting OK.

Load

A file select box will appear, and a program can be selected and
loaded into the editor.

Deflist

See the DEFLIST command.

New Names

The editor will warn you if you enter a new variable name.

Editor

Returns you to the editor.



Load (F1)

Load a GFA-BASIC 3 .GFA tokenised file.

Save (Shift F1)

Save the program as a tokenised .GFA file.

Merge (F2)

Load an ASCII text file into the editor at the cursor position.
The existing program in the editor is not erased.

Save,A (Shift F2)

Save the program in memory in ASCII format. The extension .LST
will be added to the file name. If the file already exists the old
file will be changed to .BAK.

Llist (F3)

This command controls the output of the print out. These Dot
commands have no effect on the running of the program and only
affect the printout:

.ll xx         Max line length
.pl xx         Max page length
.ff xxx        Form feed character for printer
.he text       Text to appear on first line of each page
.fo text       Text to appear on last line of each page
.lr xx         Left margin
.l-            Switch dot commands off
.l+            Switch dot commands on (default)
.n1 to .n9     Switch on line numbers up to 9 characters
.n0            Switch off line numbers
.PA            Force form feed
.P-            Do not list dot commands
.P+            List dot commands

In the header and footer text, the following can also be inserted:

\xxx           The ASCII character xxx
\d             Date
\t             Time
#              Page number

To print the symbols \ and ##, use \\ and \ respectively.

Quit (Shift F3)

Results in Do you really want to quit message. If Yes selected,
thenyou will return to the desktop.

Block (F4)

If no block marked then message Block ??? will appear. If a block
has been selected using the BlkSta and BlkEnd then the block menu
will appear:

Copy

Copies the block to current cursor position.

Move

Moves the block to current cursor position.

Write

Saves the block as an ASCII file (.LST)

Llist

Prints the block out to printer

Start

Moves the cursor to start of block

End

Moves the cursor to end of block

Del

Deletes the block

Hide

Removes the block marker

Clicking the mouse outside the Block menu or pressing a key also
removes the block marker.

New (Shift F4)

The program currently in the editor is erased from memory.


Blk End (F5)

The line before the cursor is marked as the end of block. If the
start of block marker is located before this line, the block is
shown in a different colour (or dotted background on a monochrome
screen). Also actioned with Ctrl K.

Blk Sta (Shift F5)

Marks the beginning of a block as above. Also actioned with Ctrl
B.

Find (F6)

Enter a text string to be searched for. If the string is found,
the search cab be continued with Ctrl F or Ctrl L. Also actioned
with Shift Ctrl F or Shift Ctrl L.
Folded procedures and functions are not searched.

Replace (Shift F6)

This function will replace one string of text by another. Input
the text to be replaced, then the replacement text. On finding an
occurrence, the actual replacement can be effected with Ctrl E.
Also activated with Shift Ctrl E.

Pg down (F7)

Scrolls the screen down one page. Also activated with Ctrl C.

Pg Up (Shift F7)

Scrolls the screen up one page. Also activated with Ctrl R.

Insert/Overwr (F8)

Switches between insert and overwrite.

Txt16/Text8 (Shift F8)

Only on monochrome monitor. Either 16 pixel high characters or 8
pixel high characters will provide 23 or 48 lines on the screen
respectively.

Flip (F9)

Flip between Edit and Output screen. Press any key to return to
the Edit screen

Direct (Shift F9)

Switch to Direct mode, where commands will be actioned
immediately. Some commands, such as loop commands are not
available in direct mode. Direct mode can also be entered by
pressing Esc key. The last 8 commands entered in direct mode are
remembered and can be recalled using the up and down arrow keys.
The Undo key will recall the last command.

A procedure can be called from direct mode.

Test (F10)

Tests all loops, subroutines and conditional instructions for
consistency without running the program.

Run (Shift F10)

The program in the editor memory is started. A running program can
be interrupted using Ctrl Shift Alt keys together.


Clock Display

The clock can be set by clicking on the clock and entering a new
time.

Line Numbers

Clicking on the line number box (beneath the clock) allows you to
enter a line number. On input the cursor will jump to this line
number. Also activated with Ctrl G.


COMMANDS AND FUNCTIONS
======================

The following commands and functions have been sorted by  alphabetical
order.  Each entry describes the command syntax and the action of  the
command.  Some  of the more complex commands have examples.  The  full
GFA-BASIC  Interpreter Reference manual contains examples for most  of
the commands. The advanced commands such as the operating system calls
BIOS, GEMDOS and XBIOS are not covered here and should be consulted in
the GFA-BASIC Interpreter Reference manual.

*
Syntax:    *y
Action:    returns the address of variables, but for strings or arrays
           the address of the descritpor is returned. (ARRPTR is the
           same as *).

+
Syntax:    a$+b$
Action:    Concatenation operator, to add strings together.

+          Arithmetic operator (a+b adds a and b).
*          a*b (a times b).
/          a/b (a divided by b).
^          a^b (a to the power b).
<>         a<>b (a not equal b).
<=         a<=b (a less than or equal to b).
>=         a>=b (a greater than or equal to b).


==
Syntax:    a==b
Action:    Comparison operator for approximately  equal 'a' and 'b' are
           numeric expressions. The == operator is used in the same way
           as a comparison with = but only 28  bits of the mantissa are
           compared i.e. about 8.5 digits.

@
Syntax:    @FRED
Action:    GOSUB PROCEDURE fred (@ is synonymous with GOSUB).

ABS
Syntax:    ABS(X)
Action:    Returns the absolute value of a number. (see also SGN).

ABSOLUTE
Syntax:    ABSOLUTE x,y
Action:    Assigns the address y to the variable x.

ACHAR
Syntax:    ACHAR code,x,y,font,style,angle
Action:    ASCII characters value 'code' are displayed at the graphics
           location x,y.
         Font can be:
           0 = 6x6 (Icon font).
           1 = 8x8 (Normal colour font).
           2 = 8x16 (Normal monochrome font).
         Larger values are taken to be the font header address of a
         GDOS font.
           Text type (bold, faint etc. 0-31) and output angle
           (0,900,1800,2700) can be specified.

ACLIP
Syntax:    ACLIP flag,xmin,ymin,xmax,ymax
Action:    To define a 'clipping' rectangle to which LINE-A screen
           output will be limited.
           Flag 0 = clipping off, non zero = on.

ACOS
Syntax:    ACOS(x)
Action:    Returns the arc-cosine (in radians) of x.

ADD(x,y)
Syntax:    z%=ADD(x%,y%)
Action:    Integer addition.

ADD
Syntax:    ADD x,y
Action:    Increase value of variable x by y.

ADDRIN
Syntax:    address of the AES Address Input block.
           With an index after this function, the appropriate
           parameter block is accessed directly.
           ADDRIN(2)=x is the same as
           LPOKE ADDRIN+2,x

ADDROUT    address of the AES Address Output block, see above.

AFTER ticks GOSUB proc (see also EVERY).
AFTER CONT
AFTER STOP
           Procedures can be called after the expiry of a set time.
           Time in ticks (200ths of a second).
           To continue the process, use CONT, and to stop
           use STOP.

ALERT
Syntax:    ALERT a,message$,b,button$,var
Action:    Creates an alert box
           'a' chooses type of alert symbol, 0=none, 1=!, 2=?, 3=stop
           'message$' Contains main text.
           Up to 4 lines of 30 characters/line
           lines are separated by the '|' symbol (Shift \).
           'button$'  Contains text for the buttons 'B'.
           'b' is the button to be highlighted (0,1,2,3)
           to be selected by just pressing return.
           'var' This variable is set to the number of the button
           selected.

Example:   ALERT 1,"Pick a|button",1,"Left|Right",a%
           ALERT 0,"You pressed|Button"+STR$(a%),0,"OK",a%

ALINE
Syntax:    ALINE x1,y1,x2,y2,f,ls,m
Action:    Draw a line using LINE A. x1,y1 are the start coordinates
           x2,y2 end of line. f = colour (0-15). ls = line style in 16
           bit information, (solid, dashed, dotted ..).
           m  mode
           0  Replace
           1  Transparent
           2  Inverted
           3  Inverted transparent


AND
Syntax:    x AND y
Action:    Logical operator, performs a logical AND, results in a true
           or false result.
AND()
Syntax:    AND(x,y)
Action:    See AND above.

APOLY TO
Syntax:    APOLY adr_pnt,num_pnt,y0 TO y1,f,m,addr,num_pattern
Action:    Similar to POLYFILL, draws a sequence of joined lines, with
           'num_pnt' corners, and fills the resulting area with a user
           defined pattern. 'adr_pnt' is the address of the array
           holding the alternating x,y corner coordinates. 'num_pnt'
           is the number of points. y0 and y1 specify the highest and
           lowest part of the screen where filling can occur. The
           parameters f,m,addr,num_pattern are the same as for HLINE.

APPL_EXIT
Syntax:    APPL_EXIT()
Action:    Informs the system prog has finished - this is a dummy
           function as QUIT or SYSTEM do this automatically.

APPL_FIND
Syntax:    APPL_FIND(fname$)
Action:    Returns the ID of the sought after application. Either
           returns the apps ID or -1 if it cant be found. fname$ is an
           8 character filename - without extension.

Example:    PRINT APPL_FIND("CONTROL")

           prints  -1 if it cant find the  CONTROL.ACC,  or
           returns it's ID [2].

APPL_INIT
Syntax:    APPL_INIT()
Action:    Announce the program as an application.

APPL_READ
Syntax:    APPL_READ(id,len,adr_buffer)
Action:    Instruction bytes can be read from the event buffer.
           id - id of the application from whose buffer reading is to
           be done.
           len - number of bytes to read.
           adr_buffer - address of the buffer.

APPL_TPLAY(mem,num,speed)
APPL_TRECORD(mem,num)
           APPL_TRECORD makes a record of user activities, and TPLAY
           plays these back at the specified speed (1 - 1000).
           * ONLY VALID on TOS 1.4 and above. *

APPL_WRITE
Syntax:    APPL_WRITE(id,len,adr_buffer)
Action:    Bytes are written to the event buffer. SEE APPL_READ.

ARECT
Syntax:    ARECT x1,y1,x2,y2,f,m,addr,num_pattern
Action:    Similar to PBOX, x1,y1 and x2,y2 are opposite corners of a
           rectangle. The parameters f,m,addr,num_pattern are the same
           as for HLINE.

ARRAYFILL
Syntax:    ARRAYFILL x(),n
Action:    Assigns the value 'n' to all elements of a field array
           x().

ARRPTR
Syntax:    ARRPTR(x)
Action:    Finds the address of the (6 byte long) descriptor of
           a string or field. (Same as *x)

ASC
Syntax:    ASC(x$)
Action:    Finds the ascii code of the first character of a string.

ASIN
Syntax:    ASIN(x)
Action:    Returns the arc-sine (in radians) of x.

ATEXT
Syntax:    ATEXT x,y,font,s$
Action:    Output text at x,y coordinates using A LINE.

ATN
Syntax:    ATN(x)
Action:    Returns the arc tangent of x.

BASEPAGE
Syntax:    BASEPAGE
Action:    Returns the address of the basepage of GFA-Basic.

BCHG(x,y)
BCLR(x,y)
           Allow setting and resetting of bits.
           BCLR sets the y-th bit of x to zero.

BGET
Syntax:    BGET #i,adr,cnt
Action:    Reads from a data channel into an area of memory

           'i'   \
           'adr'  -- integer expressions.
           'cnt' /            'i'       is the channel number.
           'cnt'     bytes are read in and stored in memory
                     starting at address 'adr'
           Unlike BLOAD, several different areas of memory can be
           read from a file.

BIN$
Syntax:    BIN$(x[,n])
Action:    Changes value of 'x' to a string containing the binary
           value of 'x'. The optional parameter 'n' specifies the
           number of character positions to be used (1 to 32).

BIOS
Syntax:    BIOS(n[,x,y])
Action:    To call the BIOS routine. The optional parameter list can
           be prefixed with W: or L: to denote word or longword
           parameters. (if non given, default is W:)
Example:
           REPEAT
           UNTIL BIOS(11,-1) AND 4

           Waits for the Control key to be pressed.

           Please refer to GFA-BASIC Interpreter Manual for full  list
           of BIOS calls.

BITBLT
Syntax:    BITBLT s%(),d%(),p%()
Action:    Raster copying command similar to GET and PUT but
           more flexible and faster for some applications.
           's%' the description of the source raster
           'd%' the description of the destination raster
           'p%' co-ordinates of the two equally sized rectangles
                and the copying mode (see PUT).

BLOAD/BSAVE
Syntax:    BLOAD "filename" [,address]
           BSAVE "filename",address,length
Action:    Load and save memory from and to disc drive.

Example:   DEFFILL 1,2,4
           PBOX 100,100,200,200
           BSAVE "RECT.PIC",XBIOS(2),32000
           CLS
           PRINT "IMAGE STORED. Press a key to continue"
           ~INP(2)
           CLS
           BLOAD "RECT.PIC",XBIOS(2)

BMOVE
Syntax:    BMOVE scr,dst,cnt
Action:    Fast movement of memory blocks.
           'scr' is the address at which the block to be moved
           begins.
           'dst' is the address to which the block is to moved
           'cnt' is the length of the block in bytes.

BOUNDARY
Syntax:    BOUNDARY n
Action:    Uses function vsf_perimeter to switch off (or on) borders
           on filled shapes (PBOX, PCIRCLE ..). If n is zero - no
           border, n - non zero = border.
BOX
Syntax:    BOX x,y,xx,yy
Action:    Draws a rectangle with corners at (x,y) and (xx,yy)

BPUT
Syntax:    BPUT #n,adr,cnt
Action:    Reads from an area of memory out to a data channel.
           'n' is a channel number.
           'adr' is start address of memory to read from.
           'cnt' bytes are read from address.

BSAVE      See BLOAD

BSET(x,y)  Allows setting and resetting of bits.
BTST(x,y)  BSET sets the y-th bit of x to 1.
           BTST results in -1 (TRUE) if bit y of x is set.

Example:   x=BSET(0,3)
           PRINT x,BSET(0,5)

BYTE(x)    Returns the lower 8 bits of the numerical expression x.
           (See also CARD(), WORD() ).

BYTE{x}    As  a function eg.  y=BYTE{x} one can read the contents  of
           the address x.  As a command one writes to address  x.  eg.
           BYTE{x}=y. This is similar to PEEK and POKE but is not done
           in supervisor mode.  (See also CARD{},  INT{},  LONG{}, {},
           FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).

C:
Syntax:    C:addr([ x,y,....L:x, w:y])
Action:    Calls a C or assembler program with parameters as in C. The
           parameters can be sent as 32-bit long words or 16-bit words
           to the subroutine.  eg.  a%=C:adr%(L:x,W:y,z) leads to  the
           following situation on the stack:
           (sp)     ->return address (4bytes)
           4(sp)    ->x (4 bytes)
           8(sp)    ->y (2 bytes)
           10(sp)   ->z (2 bytes)
           The value returned by the call is the contents of D0.

CALL
Syntax:    CALL addr([ x,y,....L:x, w:y])
Action:    Calls a machine code or  C  subroutine   at address 'addr'.
           When the call is made,  the return address is on the top of
           the stack, followed by the number of parameters as a 16-bit
           word,  then  the address of the parameter list as a  32-bit
           word.

CARD(x)    Returns  the lower 16 bits of the numerical  expression  x.
           (See also BYTE, WORD).

CARD{x}    Reads/writes   a  2-byte  unsigned  integer   (similar   to
           DPEEK/DPOKE). (See also BYTE{},  INT{},  LONG{}, {},
           FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).

CASE       See SELECT.

CFLOAT(x)  Changes  the integer x into a floating point  number.  (See
           also CINT).

CHAIN
Syntax:    CHAIN f$
Action:    Loads a GFA  Basic  program file into memory  and starts it
           immediately it is loaded.  If no extension is given  '.GFA'
           is assumed.

Example:   CHAIN "A:\EXAMPLE.GFA"

CHAR{x}    Reads  a string of bytes until a null byte is  encountered,
           or writes the specified string of bytes and appends a  null
           byte.

Example:   PRINT CHAR{BASEPAGE+129} prints the command line.

CHDIR
Syntax:    CHDIR "directory name"
Action:    Changes the current directory.

Example:   CHDIR "B:\TEST"

CHDRIVE
Syntax:    CHDRIVE n or n$
Action:    Sets the default disk drive 0=current, 1=A, 2=B etc.

Example:   CHDRIVE 1
           PRINT DFREE(0)
           PRINT DIR$(2)
           CHDRIVE "C:\"

CHR$(x)    Returns the character from a specified ASCII code.

Example:   PRINT CHR$(65)     !PRINTS A

CINT(x)    Changes  a  floating point number into a  rounded  integer.
           (See also CFLOAT).

CIRCLE
HOW:       CIRCLE x,y,r[,w1,w2]
Action:    Draws a circle with centre coordinates at x,y and a  radius
           r.  Additional  start  and  end angles w1  and  w2  can  be
           specified to draw a circular arc.

Example:   CIRCLE 320,200,100

CLEAR
Syntax:    CLEAR
Action:    Clears all variables and fields.

CLEARW
Syntax:    CLEARW n
Action:    Clears the contents of the window numbered 'n'

CLIP x,y,w,h [OFFSET x0,y0]
CLIP x1,y1 TO x2,y2 [OFFSET x0,y0]
CLIP #n [OFFSET x0,y0]
CLIP OFFSET x,y
CLIP OFF

           This group of commands provide 'Clipping' functions,ie. the
           limiting of graphic display within a specified  rectangular
           screen area.
           The  command  CLIP x,y,w,h defines the  clipping  rectangle
           starting  at upper left coordinates x,y and extends w  wide
           and h high.
           The  next  command  CLIP ..  TO  ..  allows  input  of  the
           diagonally opposite corners of the clipping rectangle.
           The third variant makes it possible to dfine the limits  of
           the  window  'n'.  The optional additional  command  OFFSET
           x0,y0  makes  it  possible to redefine the  origin  of  the
           graphic display. If used in its own right this command sets
           the origin for graphic display at x0,y0.
           The command CLIP OFF turns clipping off.

CLOSE
Syntax:    CLOSE [#n]
Action:    Close a data channel or a channel to a  previously   OPENed
           device.  If  the  channel number  is  omitted,  all  opened
           channels are closed.

CLOSEW
Syntax:    CLOSEW n
Action:    Closes the window numbered n.

CLR
Syntax:    CLR var [ ,var ]
Action:    Deletes and sets specified variables (not arrays) to 0.

CLS
Syntax:    CLS [#n]
Action:    Clears the screen [numbered n].

COLOR
Syntax:    COLOR color
Action:    Sets the colour for drawing/text. (0-15).

COMBIN
Syntax:    z=COMBIN(n,k)
Action:    Calculates the number of combinations of n elements to  the
           kth class without repetitions. Defined as z=n!/((n-k)!*k!).

CONT
Syntax:    CONT
Action:    Resumes execution of a program.
           Continue the execution of a program after interruption.

CONTRL     Address of the VDI control table.
           With  an  index  after  this  function,   the   appropriate
           parameter block is accessed directly.
           CONTRL(2)=x is the same as
           DPOKE CONTRL+4,x

COS
Syntax:    COS(x)
Action:    Returns the cosine of value x (radians)

COSQ(x)    Returns the cosine of value x  from  an internal  table  in
           steps  of 16th of a degree so is 10 times faster than  COS.
           (in degrees).

CRSCOL  CRSLIN
Syntax:    CRSCOL
           CRSLIN
Action:    Returns current cursor line and column. (see also PRINT
           AT).

CURVE
HOW:       CURVE x0,y0,x1,y1,x2,y2,x3,y3
Action:    The  BEZIER-Curve starts at x0,y0,  and ends at  x3,y3.
           The curve  at  x0,y0 is at a tangent with a line from
           x0,y0  to x1,y1;  and  at  x3,y3 is at a tangent with
           a  line  between x3,y3 and x2,y2.

Example:
          x0=10
          y0=10
          x1=50
          y1=110
          x2=150
          y2=200
          x3=350
          y3=300
          LINE x0,y0,x1,y1
          LINE x2,y2,x3,y3
          CURVE x0,y0,x1,y1,x2,y2,x3,y3


CVI   CVL   CVS   CVF   CVD
Syntax:    CVI(x$) .... CVD(x$)
Action:    Changes character strings into numeric variables.
      CVI  Changes a 2-byte string into an integer
      CVL     "    " 4-byte    "    "   "    "
      CVS     "    " 4-byte basic string into a floating  point number
      CVF     "    " 6-byte    "      "    "  a GFA 1 or 2    "
      CVD     "    " 8-byte    "      "    "  a GFA 3 floating point.

*******************************************************************


DATA
Syntax:    DATA [CONST[,CONST] ...]
Action:    Used as memory variables which can be read by the READ
           command. The constants are separated by commas.

Example:   For i=1 to 3
               READ A
               PRINT A
           Next i
           DATA 1,2,3,4

DATE$
Syntax:    DATE$
Action:    Returns the system date.

           DATE$=date$        Sets the system date.  (either  DD.MM.YY
                              (UK) orMM.DD.YY (US)
                              The format depends on MODE setting.

DEC
Syntax:    DEC var
Action:    Reduces the value of 'var' by 1

DEFAULT    See SELECT

DEFBIT
DEFBYT
DEFWRD
DEFFLT
DEFSTR
           The  instruction  DEFxxx  sets the varaible  type  to  that
           specified.

Example:   DEFBIT "a-z"       defines all variables as boolean.

DEFFILL
Syntax:    DEFFILL [col],[style],[pattern] or  DEFFILLL [col],A$
Action:    Sets fill colour and pattern, or allows user-defined
           patterns.
           'style' - 0=empty, 1=filled, 2=dots, 3=lines, 4=user
           24 dotted patterns and 12 lined can by chosen.
           A user-defined fill pattern is defined in the second
           variation - DEFFILL col,A$ by defining a 16 x 16 bit
           pattern array.

DEFFN
Syntax:    DEFFN func [(x1,x2,..)]=expression
Action:    Allows  the definition of single line functions.  The  term
           'expression' can be any numeric or string expression.

Example:   DEFFN test(y,a$)=x-y+LEN(a$)
           x=2
           PRINT @test(4,"abcdef")
           See also FN

DEFLINE
Syntax:    DEFLINE [style],[thickness],[begin_s,end_s]
Action:    Sets line style, width & type of line start and end.
           'style' determines the style of line:
           1 Solid line
           2 Long dashed line
           3 Dotted
           4 Dot-dashed
           5 Dashed
           6 Dash dot dot ..
           7 User defined
           'thickness' sets width in pixels (odd numbers only).
           The  start  and  end  symbols  are  defined  by  the   last
           parameter, and can be:
           0 Square
           1 Arrow
           2 Round


DEFLIST
Syntax:    DEFLIST x
Action:    Defines the program listing format.
           x   Command   Variable
           0   PRINT     abc
           1   Print     Abc
           2   PRINT     abc#
           3   Print     Abc#

DEFMARK
Syntax:    DEFMARK [C],[A],[G]
Action:    Sets colour,type and size of the corner points to be
           mark using the command polymark
           'C' is the colour register number
           'A' defines the type of mark. the following types
           are possible :-
           1=dot
           2=plus sign
           3=asterisk
           4=square
           5=cross
           6=hash
           all other values return the asterisk symbol
           'G' sets the size of mark

DEFMOUSE
Syntax:    DEFMOUSE n or  DEFMOUSE a$
Action:    Chooses a pre-defined mouse form or defines a new one
           the following mouse forms are available :-

           0=arrow             1=expanded (rounded) X
           2=bee               3=pointing hand
           4=open hand         5=thin crosswire
           6=thick crosswire   7=bordered crosswire

           A mouse can be defined by the command defmouse a$
           16*16 dots are available to create a shape. Also
           a 'mask' must be defined so that the cursor remains
           visible when it is the same colour as the background
           one of the 256 dots must be defined as the starting
           point to which the mouse functions will relate.

Example:
           DEFMOUSE 2
           PAUSE 1
           m$=MKI$(0)+MKI$(0)+MKI$(1)+MKI$(0)+MKI$(1)
           FOR i%=1 TO 16
              m$=m$+MKI$(65535)
           NEXT I%
           FOR i%=1 TO 16
              m$=m$+MKI$(1)
           NEXT i%
           PBOX 200,150,400,250
           DEFMOUSE m$
           REPEAT
           UNTIL MOUSEK
DEFNUM
Syntax:    DEFNUM n
Action:    Affects  output  of numbers by the PRINT  command  and  its
           variants.  All numbers are outputted to occupy n  character
           positions, not counting the decimal point.


DEFTEXT
Syntax:    DEFTEXT [colour],[attr],[angle],[height],[fontnr]
Action:    Defines the colour,style,rotation and size of text
           to be printed using the text command.

           'colour' colour register number (0-15).
           'attr' text style - 0=normal 1=bold 2=light 4=italic
           8=underlined 16=outlined (can be combined).
           'angle'= rotation only the following  are possible :-
           0 deg (0), 90 deg (900), 180 deg (1800), 270 deg (2700)
           'height' size of text - 4=icon, 6=8*8, 13=std, 32=enlarged.
           'fontnr' - the number of a desired character set. This font
           must  have  been  previously  installed  (See  also   GDOS,
           VST_LOAD_FONT, VQT_NAME).

Example:
           FOR i%|=0 TO 5
              DEFTEXT 1,2^i|,0,13
              TEXT 100,i|*16+100,"This is text attribute "+STR$(i|)
           NEXT i|


DEG(x)     Converts x from radians to degrees. See also RAD.

DELAY x    Suspends   program   operation  for  x  seconds   (with   a
           theroetical resolution in milliseconds). See aslo PAUSE.

DELETE
Syntax:    DELETE x(i)
Action:    Removes  the ith element of array x.  All elements  with  a
           larger  index  are  shifted down  one  position.  See  also
           INSERT.

DFREE
Syntax:    DFREE(n)
Action:    Locates free space on a disc 'n' = drive number (0-15)

DIM
Syntax:    DIM var(indices)[,var(indices),.....]
Action:    Sets the dimensions of an array or string array.

DIM?
Syntax:    DIM?(field())
Action:    Determines the number of elements in an array.
           Note - arrays have an element '0'.

DIR
Syntax:    DIR "filespec" [TO "file"]
Action:    Lists the files on a disc.  The output can be directed to a
           file or other device.

Example:   "LST:" See also FILES.

DIR$
Syntax:    DIR$(n)
Action:    Names the active directory for drive 'n'
           'n' is drive number (1=A:, 2=B: ...).

DIV
Syntax:    DIV var,n
Action:    Divides the value of var by n. As var=var/n but 30% faster.

DIV()
Syntax:    a%=DIV(x,y)
Action:    See DIV above.


DMACONTROL
Syntax:    DMACONTROL ctrlvar
Action:    Controls the DMA sound on the STE.
           cntrlvar = 0 - stop sound
                      1 - Play sound once
                      2 - Play sound in a loop

DMASOUND
Syntax:    DMASOUND beg,end,rate[,ctrl]
Action:    Output of DMA sampled sound on the STE.
           beg  - Sample start address.
           end  - Sample end address.
           rate - Sample rate 0=6.25 kHz,  1=12.5 kHz, 2=25 kHz,
                  3=50kHz.
           ctrl - See DMACONTROL above.

Example:   'Try each of the DMASOUND lines below.
           n%=360*32
           DIM a|(n%)
           'DMASOUND V:a|(0),V:a|(n%),0
           'DMASOUND V:a|(0),V:a|(n%),1
           'DMASOUND V:a|(0),V:a|(n%),2
           DMASOUND V:a|(0),V:a|(n%),3,3
           FOR i%=0 TO n%
            a|(i%)=128+SINQ(i%*i%/7200)*127
           NEXT i%
           REPEAT
           UNTIL MOUSEK
           DMACONTROL 0


DO....LOOP
Syntax:    DO
           (instructions)
           LOOP
Action:    Creates an endless loop, exit only with EXIT IF or GOTO.

DO UNTIL condition
DO WHILE condition

           The  commands DO and LOOP can be extended using  UNTIL  and
           WHILE.  The  loop  DO WHILE causes a loop as  long  as  the
           condition is true. See also LOOP WHILE, LOOP UNTIL.

DOUBLE{x}  Reads/writes  an  8-byte floating point  variable  in  IEEE
           double precision format.  (See also BYTE{},  CARD{}, INT{},
           LONG{}, {}, FLOAT{}, SINGLE{}, CHAR{} )


DOWNTO     Used within a FOR..NEXT loop as a counter. Instead of using
           step -1,  the command DOWNTO is used,  however STEP is  not
           possible with DOWNTO. eg:
           FOR c=100 DOWNTO 1
           is the same as FOR c=100 TO 1 STEP -1


DPEEK(x)   Reads 2 bytes from address x (a word).  Works in supervisor
           mode.

DPOKE x,y  Writes  y  as  a 2 byte word to  address  x.  To  work  in
           supervisor mode use SDPOKE ..


DRAW
Syntax:    DRAW [TO] [x,y]
           DRAW [x1,y1][TO x2,y2][TO x3,y3][TO..]
Action:    Draws points and connects two or more points with
           straight lines. DRAW x,y is the same as PLOT x,y.
           DRAW TO x,y connects the point to the last set
           point (set by PLOT, LINE or DRAW).

DRAW expression
DRAW(i)
SETDRAW
           These instructions give a turtle like approach to  drawing.
           An  imaginary  pen  is  moved over  the  screen  and  draws
           relative to the last point. The 'expression' is a LOGO type
           of  convention  controlled by  graphic  commands.  The  pen
           leaving  a trail over the 'paper' leaves a  graphic  image.
           The statement below is an wxample of how these commands can
           be used.

Example:   DRAW  "PU FD 40 PD FD 40"

           The available commands are:

FD n       ForwarD            Moves the 'pen' n pixels forward

BK n       BacKward           Moves the 'pen' n pixels backwards

SX x       Scale x            Scales the 'pen' movement for FD and BK

SY y       Scale y            by the specified factor.  Use SX0 or SY0
                              to turn off scaling.

LT a       Left turn          Turns   the  'pen'  left   through   the
                              specified angle a, given in degrees.

RT a       Right turn         As LT but turns right.

TT a       Turn To            Turns  the 'pen' to the  absolute  angle
                              'a' in degrees. (see below)

                               0
                               |
                               |
                     270 -- zero point -- 90
                               |
                               |
                              180


MA x,y     Move Absolute      Moves  the  'pen'  to   the   absolute
                              coordinates x,y

DA x,y     Draw Absolute      Moves  the  'pen'  to   the   absolute
                              coordinates x,y and draws a line in  the
                              current colour from the last position to
                              the point x,y

MR xr,yr   Move Relative      Moves the 'pen' position in the x and  y
                              directions   relative   to   the    last
                              position.

DR xr,yr   Draw  Relative     Moves  the  'pen'  by   the   specified
                              displacement   relative  to   its   last
                              position and draws a line in the current
                              colour  from the last position  to  this
                              point.

The  command SETDRAW x,y,w is an abbreviation for the expression
DRAW "MA",x,y,"TT",w.

CO  c      Colour             Sets 'c' as the character  colour  (see
                              parameters for COLOR command).

PU         Pen Up             Lifts the 'pen' from the 'paper'.

PD         Pen Down           Lowers the 'pen' onto the 'paper'.

Additionally the following interrogation functions are available:

DRAW(0)    returns the x position.
DRAW(1)    returns the y position.
DRAW(2)    returns angle in degrees.
DRAW(3)    returns the X axis scale factor.
DRAW(4)    returns the Y axis scale factor.
DRAW(5)    returns the pen flag (-1=PD, 0=PU).

All these functions return floating point values.

Example:

           DRAW "ma 160,200 tt 0"
           FOR i&=3 TO 10
             polygon(i&,90)
           NEXT i&

           PROCEDURE polygon(n&,r&)
           LOCAL i&
           FOR i&=1 TO n&
             DRAW "fd",r&," rt ",360/n&
           NEXT i&
           RETURN

EDIT
Syntax:    EDIT
Action:    Returns to the editor.
           When used in direct mode the command allows a return
           to the editor. In a program, is the same as END but
           without the program end alert box.

ELLIPSE
Syntax:    ELLIPSE x,y,rx,ry [,phi0,phi1]
Action:    Draws an ellipse at x,y, having 'rx' as length of the
           horizontal axis and 'ry' as length of the vertical axis
           The optional angles 'phi0' & 'phi1' give start and end
           angles in tenths of a degree, to create an elliptical arc.

ELSE       See command IF.
ELSE IF     "     "    "


END
Syntax:    END
Action:    Closes all files and terminates program execution.


ENDFUNC    See command FN.

ENDIF      See command IF.

ENDSELECT  See command SELECT.


EOF
Syntax:    EOF (#n)
Action:    Determines whether the file pointer for the file with
           channel number 'n' is at End Of the File.  Returns -1 if it
           is, otherwise 0.


EQV
Syntax:    x EQV y
Action:    The operator EQV (equivalence) produces a TRUE result  only
           if  the  arguments of both are either TRUE or  both  FALSE.
           (same as NOT(x XOR y)).

EQV(x,y)
Syntax:    EQV(x,y)
Action:    Sets a bit of the result if the appropraite bits in x and y
           are both set, or both reset. eg:
           PRINT BIN$(EQV(15,6),4) prints 0110


ERASE
Syntax:    ERASE field()
Action:    Deletes an array and releases the dimensioned area.


ERR
Syntax:    ERR
Action:    Returns the error code of any error that has occurred.

ERR$
Syntax:    ERR$(x)
Action:    Returns, as a string, the GFA Basic error mesage x.

ERROR
Syntax:    ERROR n
Action:    Simulates the occurrence of the error with the error
           code 'n' and the appropriate error message is then
           displayed.



EVEN
Syntax:    EVEN n
Action:    Determines if a number is even.   Returns  TRUE  (-1)   and
           FALSE(0). Also see ODD


EVERY
EVERY CONT
EVERY STOP

Syntax:    EVERY ticks GOSUB proc
Action:    The command EVERY causes the procedure 'proc' to be  called
           every 'ticks' clock units. The clock unit is defined as one
           two-hundredth  of a second.  But a branch can only be  done
           every  fourth clock unit,  resulting in an  effective  time
           resolution of one fiftieth of a second.
           Using  EVERY  STOP,  the  calling of a   procedure  can  be
           prevented.  With EVERY CONT this is again allowed. See also
           AFTER.


EVNT_BUTTON
Syntax:    EVNT_BUTTON(clicks,mask,state[,mx,my,button,k_state])
Action:    Waits for one or more mouse clicks,  and returns the number
           of clicks.
           INPUTS
           clicks - Maximum allowable clicks.
           mask   - Mask for the desired mouse key:
                    Bit 0 = 1 : Left Button
                    Bit 1 = 1 : Right Button
           state  - Desired status,  in order to terminate the  event.
                    Bit allocation as for mask.
           RETURNED VALUES:
           mx     - x coordinate of mouse pointer on event termination
           my     - y coordinate of mouse pointer on event termination
           button - state of mouse button, bit allocation as for mask.

           k_state- Condition of keyboard shift keys:
                    Bit 0 = Right shift key
                    Bit 1 = Left shift key
                    Bit 2 = Control key
                    Bit 3 = Alternate key

EVNT_DCLICK
Syntax:    EVNT_DCLICK(new,get_set)
Action:    Sets the speed for double-clicks of a mouse button.
           Returns the speed.
           new - new speed (0-4)
           get_set - determine whether to set or read. 0=read,1=set.


EVNT_KEYBD
Syntax:    EVNT_KEYBD()
Action:    Waits  for  a key to be pressed and  returns  a  word-sized
           value. The low order byte contains the ASCII code, the high
           byte contains the keyboard scan code.


EVNT_MESAG
Syntax:    EVNT_MESAG(adr_buffer)
Action:    Waits for the arrival of a message in the event buffer. The
           returned value is always 1.
           adr_buffer  is  the  address of a 16 byte  buffer  for  the
           message.  If  0 is used,  then the sytem message buffer  is
           used, ie. MENU(1) to MENU(8).


EVNT_MOUSE
Syntax:    EVNT_MOUSE(flag,mx,my,mw,mh,mcur_x,mcur_y,button,k_state)
Action:    Waits  for  the  mouse pointer to  be  located  inside  (or
           optionally,  outside)  a specified rectangular area of  the
           screen.
           The returned value is always 1.
           INPUTS:
           flag  - Presence inside(0) or outside(1) the desired area.
           mx,my - Coordinates of top left corner of recatngle.
           mw    - Width of rectangle.
           mh    - Height of rectangle.
           OUTPUTS:
           mcur_x   x coordinate of mouse when event occurs.
           mcur_y   y coordinate of mouse when event occurs.
           button   same as for mask in EVNT_BUTTON.
           k_state  same as for k_state in EVNT_BUTTON.


EVNT_MULTI
HOW:       EVNT_MULTI(flag,clicks,mask,state,m1_flags,m1_x,
           m1_y,m1_w,m1_h,m2_flags,m2_x,m2_y,m2_w,m2_h,adr_buffer,
           count[,mcur_x,mcur_y,button,k_state,key,num_clicks])
Action:    Waits  for the occurence of selected  events.  Returns  the
           event  which actually occured,  with bit allocation as  for
           'flag' below:
           INPUT:
           flag     Sets the event(s) to be waited for as follows:
                    BIT 0 keyboard           MU_KEYBD
                    BIT 1 mouse button       MU_BUTTON
                    BIT 2 first mouse event  MU_M1
                    BIT 3 second mouse event MU_M2
                    BIT 4 report event       MU_MESAG
                    BIT 5 timer              MU_TIMER
           OUTPUT:
           num_clicks: number of expected mouse clicks

           The parameters are already described for EVNT_MESAG, etc..
           With  ON  MENU,  which uses this  routine  internally,  the
           parameters  are installed for the instruction ON  MENU  xxx
           GOSUB.
           MENU(1) to MENU(8)  Message buffer.
           MENU(9)             Returned value.
           MENU(10)=mcur_x     x mouse position.
           MENU(11)=mcur_y     y mouse pos.
           MENU(12)=button     Mouse state button.
           MENU(13)=k_state    Shift key status.
           MENU(14)=key        ASCII and scan code.
           MENU(15)=num_clicks Number of mouse clicks.


EVNT_TIMER
Syntax:    EVNT_TIMER(count)
Action:    The  function  waits  for a period  of  time  expressed  in
           'count' millisecondes.
           The returned value is always 1.


EXEC
Syntax:    EXEC flg,name,cmd,env
           EXEC (flg,name,cmd,env)
Action:    Loads and executes machine code programs or compiled
           programs from disc.
           flg=0 - load and go.
           flg=3 - load only.
           'name' - the name of the program.
           'cmd'  - command line (see BASEPAGE).
           'env'  - environment string (usually just "").
           The named program is loaded from disc, the absolute
           addresses are relocated, a basepage is created, and if
           required the program run.


EXIST
Syntax:    EXIST ("filespec")
Action:    Determines whether a particular file is present on
           a disc. If present -1 is returned, else 0 is returned.


EXIT
Syntax:    EXIT IF Condition
Action:    Enables the exit from a loop.
           If the EXIT command is met within a loop and the exit
           condition is met, the program continues from the first
           command after the loop.
           This command allows any loop to be left ie: FOR...NEXT
           DO...LOOP,  REPEAT...UNTIL AND  WHILE...WEND.


EXP
Syntax:    EXP(X)
Action:    Calculates the value of an exponent x.


FACT
Syntax:    x=FACT(n)
Action:    Calculates  the factorial (n!) of n and returns the  result
           in x. (0!=1).


FALSE
Syntax:    FALSE
Action:    Constant 0. This is simply another way of expressing
           the value of a condition when it is false and is equal
           to zero (see also TRUE).


FATAL
Syntax:    FATAL
Action:    Returns the value 0 or -1 according to the type of
           error.
           On normal errors the function returns 0. The value -1
           is returned on all errors where the address of the
           last executed command is no longer known.
           Normally this is an operating system error which
           would lead to the 'bomb' errors and the breakdown of
           the program.



FGETDTA
Syntax:    n%=FGETDTA()
Action:    Returns the DTA (Disk Transfer Address).


FIELD
Syntax:    FIELD #n,num AS svar$ [,num AS svar$,...]
           FIELD #n,num AT(x)[,num AT(x),...]
Action:    Divides records into fields.
           'n' is the channel number of a file previously OPENed.
           The integer expression 'num' determines the field length.
           'Svar' is a string variable containing  data for one  field
           of a data record.
           The section 'num AS svar$' can be repeated if the
           record is to be divided into several fields. The sum of
           the fields should equal the record length.
           By using AT() instead of AS,  numeric variables can be read
           and  written.  'num'  contains the length of  the  varaible
           type. The brackets contain a pointer to the variable.
           eg:
           FIELD #2,4 AS a$,2 AT(*b&),8 AT(*c#),6 AS d$


FILES
Syntax:    FILES p$ [TO name$]
Action:    Lists the files on a disk.
           Like DIR but more detailed data listing.


FILESELECT
Syntax:    FILESELECT [#title$],path$,default$,name$
Action:    Creates a fileselect box on the screen.
           Title$  can  be a string of max  30  characters.  Allows  a
           header  to  be placed in the fileselect box  (TOS  1.4  and
           above).
           path$  is the drive and path - if none specified  then  the
           default drive is assumed.
           default$  contains the name of the file to apppear  in  the
           selection line. ("" for no default).
           name$ contains the selected file, either an empty string if
           CANCEL is selected, or the file name selected.
           See also FSEL_INPUT

Example:
                   FILESELECT #"LOAD File","A:\*.PRG","GFABASIC.PRG",name$



FILL
Syntax:    FILL x,y
Action:    Fills a bordered area with a pattern commencing at
           the co-ordinates 'x,y'.
           Fill pattern can be chosen with the command DEFFILL.


FIX
Syntax:    FIX(x)
Action:    Returns the integer of 'x' after it has been rounded.
           Same as INT(x) for positive numbers but for negative
           numbers INT(-1.99)=-2 AND FIX(-1.99)=1.
           FIX is identical to the function TRUNC and complements
           FRAC.


FLOAT{x}   Reads/writes an 8-byte variable in Basic v3 floating  point
           format.   (See  also  BYTE{},   CARD{},  INT{},LONG{},  {},
           SINGLE{}, DOUBLE{}, CHAR{} )

FN
Syntax:    FN func[(y1,y2...)]
Action:    Call  to a defined DEFFN function or a FUNCTION.  (you  can
           also use @). See also DEFFN, FUNCTION.


FOR...NEXT
Syntax:    FOR c=b TO e [STEP s]
           instructions
           NEXT c
Action:    Creates a loop which is executed as many times as specified
           at the beginning of the loop.


FORM INPUT
Syntax:    FORM INPUT n,a$
Action:    Enables the insertion of a character string (limited
           to 255 characters in length) during program execution.
           'n' = the maximum length of the character string.
           a$ is the name of the string variable.

FORM INPUT AS
Syntax:    FORM INPUT n AS a$
Action:    Similar  to FORM INPUT,  except the current value of a$  is
           displayed, and can be edited.


***  the  following  7  commands are part  of  the  AES  FORM  Library
commands,  and  are  similar  to  C bindings  for  calling  these  AES
functions ***

FORM_ALERT
Syntax:    a%=FORM_ALERT(button,string$)
Action:    Creates an alert box.
           button  = number of the default button (0-3).
           string$ = string defining the message in the alert.  (in  C
           format)  -  note that the square brackets are part  of  the
           string:
           [i][Message][Buttons]
           where i = the required alert symbol - see ALERT.
           Message is a string max 30 characters.
           Buttons = the name of the 3 buttons.
           A good use of this command is in trapping errors:

Example:   ~FORM_ALERT(1,ERR$(ERR))


FORM_BUTTON
Syntax:    FORM_BUTTON(tree,obj,clicks,new_obj)
Action:    Make inputs in a form possible using the mouse.
           INPUTS:
           tree   -  address of the object tree
           obj    -  current object number
           clicks -  max expected number of mouse clicks
           OUTPUT:
           new_obj-  next object to be edited.
           Returns 0 if the FORM was exited, otherwise >0.

FORM_CENTER
Syntax:    FORM_CENTER(tree,fx,fy,fw,fh)
Action:    Centers the tree, and returns its coordinates.
           INPUT: tree  - address of the object tree.
           OUTPUTS:
           fx,fy    coordinates of top left corner
           fw,fh    form width and height.
           returns a reserved value (always 1).


FORM_DIAL
HOW:       FORM_DIAL(flag,mi_x,mi_y,mi_w,mi_h,ma_x,ma_y,ma_w,ma_h)
Action:    Release (or reserve) a rectangular screen area and draw  an
           expanding/shrinking rectangle.
           Returns 0 if an error occured.
           flag     function
           0        FMD_START   reserve a display area.
           1        FMD_GROW    draw expanding box.
           2        FMD_SHRINK  draw shrinking box.
           3        FMD_FINISH  release reserved display area.
           mi_x,mi_y  top left corner of rectangle at min size
           mi_w,mi_h  width & height  "     "       "  "    "
           ma_x,ma_y  top left corner of rectangle at max size
           ma_w,ma_h  width & height   "     "      "  "    "


FORM_DO
Syntax:    FORM_DO(tree,start_obj)
Action:    Pass  management  of FORM over to the AES until  an  object
           with EXIT or TOUCH EXIT status is clicked on.
           Returns  the number of the object whose clicking or  double
           clicking  caused the function to end.  If it was  a  double
           click, bit 15 will be set.
           tree      = address of the object tree.
           start_obj = Number of the first editable field (if there is
           one).


FORM_ERROR
Syntax:    FORM_ERROR(err)
Action:    Displays the ALERT associated with the error numbered err.

Example:   PRINT FORM_ERROR(10)


FORM_KEYBD
Syntax:    FORM_KEYBD(tree,obj,next_obj,char,new_obj,next_char)
Action:    Allows a form to be edited via the keyboard.
           Returns 0 if the FORM was exited, otherwise >0.
           tree     address of the object tree
           obj      number of the object to be edited
           next_obj number of the next EDITable object in the tree
           char     input character
           new_obj  object to be EDITed on the next call
           returns next_char - next character (derived from keyboard)

           This function is a subroutine of FORM_DO.


FRAC
Syntax:    FRAC(x)
Action:    Returns the digits after the decimal point in a number.
           'x' can be any numeric expression. if 'X' is an integer
           then a zero is returned,  therefore FRAC(x)=x-TRUNC(x)


FRE
Syntax:    f%=FRE(X) or f%=FRE()
Action:    Returns the amount of memory free (in bytes).
           The parameter 'x' is disregarded, but if present a 'Garbage
           Collection' is carried out.  (non current strings are freed
           from memory).


FSEL_INPUT
Syntax:    n%=FSEL_INPUT(path$,name$,[button])
Action:    Calls   the   AES  fileselect   library,   to   provide   a
           fileselector.
           The optional parameter 'button':
           Returns  a  1 or 0 depending whether 'OK' or  'Cancel'  was
           clicked on.
           ON ENTRY:
           path$    = initial directory path
           name$    = Default name
           ON EXIT:
           path$    = final directory path
           name$    = chosen filename.
           button   = 1 if 'OK'
                    = 0 if 'Cancel'


FSETDTA
Syntax:    ~FSETDTA(addr)
Action:    Sets the address of the DTA. (See also FGETDTA).


FSFIRST
Syntax:    FSFIRST(p$,attr)
Action:    Searches  for  the  first file on a  disk  to  fulfill  the
           criteria specified in p$ (eg:  "C:\*.GFA").  If found,  the
           filename and attributes are to be found in the DTA.
           The parameter 'attr' is the file atributes to search on.

FSNEXT
Syntax:    FSNEXT()
Action:    Search  for the next file which fulfills the conditions  of
           FSFIRST.

Example:
           ~FSETDTA(BASEPAGE+128)
           e%=FSFIRST("\*.GFA",-1)           ! all bits set
           DO UNTIL e%
             IF BYTE{BASEPAGE+149} AND 16    !if its a folder
               PRINT "*";CHAR{BASEPAGE+158}  ! indicate by a star
             ELSE                            ! otherwise
               PRINT 'CHAR{BASEPAGE+158}     ! a space before
           '                                 ! the filename
             ENDIF
             e%=FSNEXT()                     ! continue search
           LOOP


FULLW
Syntax:    FULLW [#]n
Action:    Enlarges window 'n' to full screen size.
           'n' is the window number. If the window has not
           yet been opened, this takes place automatically.


FUNCTION
           The commands FUNCTION and ENDFUNC form a subroutine,  in  a
           similar  manner to PROCEDURE.  The name of  the  subroutine
           and,  optionally,  the  list of varaibles are  given  after
           FUNCTION command. Calling the subroutine is done by the use
           of  @  or FN and the function name followed by  a  list  of
           parameters if necessary.
           If the command RETURN is met during program execution,  the
           the value given after it or the value of the named variable
           is  returned.  In a function,  RETURN can be  used  several
           times, with IF or the like. A function cannot be terminated
           without a RETURN command being before the ENDFUNC  command.
           In a function name ending with the $ character the function
           returns a string result.
Example:
           f1%=@fac_loop(15)
           PRINT "loop: fac(15) = ";f1%
           '
           FUNCTION fac_loop(f%)
            w=1
            FOR J%=1 TO f%
              MUL w,j%
            NEXT j%
            RETURN w
           ENDFUNC


GB         Address of the AES Parameter Block
           This  (unlike the other AES address blocks) cannot be  used
           with index.


GCONTRL    Address of the AES control block.  With index  (GCONTRL(2))
           the elements can be accessed directly.


GDOS?      Returns  TRUE  (-1)  if GDOS is  resident  and   FALSE  (0)
           otherwise.


GEMDOS
Syntax:    GEMDOS(n[,x,y])
Action:    To  call the GEMDOS routines.  The optional parameter  list
           can be prefixed with W:  or L:  to denote word or  longword
           parameters. (if non given, default is W:)

Example:
           DO UNTIL GEMDOS(17)
             ALERT 1,"Printer not ready",1,"retry|break",d%
           LOOP UNTIL d%=2


GEMSYS
Syntax:    GEMSYS n
Action:    Calls the AES routine 'n'. The parameters necessary for the
           operation  of  the  routine must first  be  placed  in  the
           appropriate AES parameter blocks.



GET
Syntax:    GET x1,y1,x2,y2,sections$
Action:    GET  puts  a section of the screen into a  string  variable
           'section$'  (x1,y1 and x2,y2 are coordinates of  diagonally
           opposite corners). See also PUT.


GET #
Syntax:    GET #n[,r]
Action:    Reads a record from a random access file.
           'n' is the channel number (1 to 99)
           'r' is number of the record to be read (1 to 65535)
           If 'r' is not given then the next record in the file
           will be read. (See also PUT #).


GETSIZE
Syntax:    bytes%=GETSIZE(x1,y1,x2,y2)
Action:    The  TT  does not have a constant screen  memory  of  32000
           Bytes like  the ST. A screen could require much more memory
           (153600  Bytes).  The commands GET and PUT are  limited  to
           32000  Bytes and therefore  a function has been  introduced
           to support the larger screen  resolutions that require more
           than 32000 Bytes.
           This  function will return the number of Bytes required  by
           the   screen between the coordinates  x1,y1,x2,y2.  Several
           GET  or PUT  commands could be used to address  the  entire
           screen.


GINTIN     Address of the AES Integer input block.  (Can be used  with
           index GINTIN(0)).

GINTOUT    Address of the AES Integer output block. (Can be used  with
           index GINTOUT(0)).


GOSUB
Syntax:    GOSUB name [ (LIST OF EXPRESSIONS) ]
Action:    Branches to the procedure called 'name'.
           A procedure name can begin with a digit and contain
           letters, numbers, dots and the underline dash.
           '(list of expressions)' contains the values of any
           local variables to be passed to the procedure.
           When the interpreter comes across a GOSUB command,
           it branches to the procedure named in the gosub.
           It is possible to call further procedures whilst in
           a procedure. It is even possible to call the procedure
           one is in at the time (recursive call).


GOTO
Syntax:    GOTO label
Action:    allows an unconditional jump to a label.
           'label' must end in a colon and can consist of letters,
           numbers, dots, dashes and can begin with a digit.


*** The following 10 functions form the Graphics library calls to  the
AES.

GRAF_DRAGBOX
Syntax:    GRAF_DRAGBOX(iw,ih,ix,iy,rx,,ry,rw,rh[,last_ix,last_iy])
Action:    Allows  a rectangle to be moved about the screen  with  the
           mouse.  Its  movement  is restricted to the interior  of  a
           larger  specified rectangle.  This function should only  be
           called  when  the left mouse button is  held  down,  as  it
           terminates when the button is released.
           Returns 0 if an error occurs.
           INPUTS:
           iw,ih    width & height of the moving rectangle
           ix,iy    initial  coords  of  top  left  corner  of  moving
                    rectangle
           rx,ry    coords of top left corner of limiting rectangle
           rw,rh    width & height of limiting rectangle
           OUTPUTS:
           last_ix  coords of top left corner of inside rectangle
           last_iy  when the function terminated.


GRAF_GROWBOX
Syntax:    GRAF_GROWBOX(sx,sy,sw,sh,dx,dy,dw,dh)
Action:    Draws an expanding rectangle.
           Returns 0 if error occurs.
           sx,sy    Initial coords of top left corner of rectangle
           sw,sh    Initial width & height of rectangle
           dx,dy    Final coords of top left corner
           dw,dh    Final width & height

GRAF_HANDLE
Syntax:    GRAF_HANDLE(char_w,char_h,box_w,box_h)
Action:    Returns  the ID number of the current VDI  workstation  and
           supplies the size of a character from the system set.
           OUTPUTS:
           char_w   width in pixels of a character
           char_h   height
           box_w    width of a character cell
           box_h    height


GRAF_MKSTATE
Syntax:    GRAF_MKSTATE(mx,my,m_state,k_state)
Action:    This  function supplies the current mouse  coordinates  and
           status of tht mouse buttons and shift keys.
           Returns a reserved value (always 1)
           OUTPUTS:
           mx,my    mouse coordinates
           m_state  mouse button status
                    bit 0 left button
                    bit 1 right button
           k_state  see k_state in function EVNT_BUTTON


GRAF_MOUSE
Syntax:    GRAF_MOUSE(m_form,pattern_adr)
Action:    This  function  allows  the  mouse  shape  to  be  changed.
           (similar command to DEFMOUSE)
           Returns 0 if an error occurs.
           m_form   number of the mouse pointer shape
               0    = Arrow
               1    = Double curly brackets
               2    = Busy bee
               3    = Pointing finger
               4    = Open hand
               5    = Thin cross hairs
               6    = Thick cross hairs
               7    = Outlined cross hairs
               255  = User defined
               256  = Hide mouse
               257  = Show mouse

           pattern_adr = address of bit information defining the mouse
                         pointer. 37 word-sized values as follows:
                    1 =  x coordinate of the action point
                    2 =  y     "      "   "    "      "
                    3 =  number of colour levels, always 1
                    4 =  mask colour, always 0
                    5 =  pointer colour, always 1
              6 to 21 =  Mask definition (16 words ie.16x16 bits)
             22 to 37 =  Pointer def              "


GRAF_MOVEBOX
Syntax:    GRAF_MOVEBOX(w,h,sx,sy,dx,dy)
Action:    Draws a moving rectangle with constant width & height.
           Returns 0 on error.
           INPUTS:
           w,h      width & height of rectangle
           sx,sy    Initial coords of top left corner of rectangle
           dx,dy    Final coords of top left corner


GRAF_RUBBERBOX
Syntax:    GRAF_RUBBERBOX(tx,ty,min_w,min_h[,last_w,last_h])
Action:    This function draws an outline of a rectangle while the the
           left  mouse  button is held down.  The top left  corner  is
           fixed,  but the width & height of the rectangle change with
           the  position of the mouse.  This function should  only  be
           called  when  the left mouse button is  held  down,  as  it
           terminates when the button is released.
           Returns 0 if an error occurs.
           INPUTS:
           tx,ty         coords of top left corner
           min_w,min_h   minimum width & height of rectangle
           OUTPUTS:
           last_w        width of rectangle when function terminates
           last_h        height "     "       "     "          "


GRAF_SHRINKBOX
Syntax:    GRAF_SHRINKBOX(sx,sy,sw,sh,dx,dy,dw,dh)
Action:    Draws an shrinking rectangle.
           Returns 0 if error occurs.
           sx,sy    Final coords of top left corner
           sw,sh    Final width & height
           dx,dy    Initial coords of top left corner of rectangle
           dw,dh    Initial width & height of rectangle



GRAF_SLIDEBOX
Syntax:    GRAF_SLIDEBOX(tree,parent_obj,slider_obj,flag)
Action:    This function (really belongs to the OBJECT library)  moves
           one rectangular object within another,  in a similar manner
           to GRAF_DRAGBOX. The object can only be moved vertically or
           horizontally, and must be a 'child' of the limiting object.
           This  function  should only be called when the  left  mouse
           button  is held down,  as it terminates when the button  is
           released.  Commonly  used  in movement of  slider  bars  in
           windows.
           Returns  the position of the moving rectangle  relative  to
           the limiting one:
           Horizontally: 0 = far left    1000 = far right
           Vertically:   0 = top         1000 = bottom
           INPUTS:
           tree          address of oobject tree
           parent_obj    object number of the 'limiting rectangle'
           slider_obj       "     "    "   "   moving rectangle
           flag          direction (0=horizontal, 1=vertical)



GRAF_WATCHBOX
Syntax:    GRAF_WATCHBOX(tree,obj,in_state,out_state)
Action:    This  function  (really  belongs  to  the  OBJECT  library)
           monitors  an object tree while a mouse button  is  pressed,
           checking  whether the mouse pointer is inside  or  outside.
           When the mouse button is released, the status of the object
           takes one of two specified values (normal selected/normal),
           depending  on whether the pointer was inside the object  or
           outside.
           Returns  1 if the mouse pointer was inside the object  when
           the button was released, or 0 if it was outside.
           INPUTS:
           tree       address of the tree
           obj        number of the object to be monitored
           in_state   Status (OB_STATE) to be given to the  object  if
                      the mouse pointer is found within it.
           out_state  Status (OB_STATE) to be given to the  object  if
                      the mouse pointer is found outside it.


GRAPHMODE
Syntax:    GRAPHMODE n
Action:    Sets the graphic mode 1 to 4.
           1=replace     2=transparent
           3=xor         4=reverse transparent


HARDCOPY
Syntax:    HARDCOPY
Action:    Prints the screen (same as pressing <ALT> & <HELP>).


HEX$
Syntax:    HEX$(x[,y])
Action:    Changes the value of 'x' into a string expression
           which contains the value of 'x' in hexadecimal form.
           The optional parameter y specifies the number of  character
           positions (1 to 8) to be used.


HIDEM
Syntax:    HIDEM
Action:    Switches off the mouse pointer. (see also SHOWM).


HIMEM
Syntax:    HIMEM
Action:    Returns the address of the area of memory which is  not
           required by GFA Basic.   Normally  16384  bytes  below  the
           screen.


HLINE
Syntax:    HLINE x1,y,x2,f,m,addr,num_pattern
Action:    Similar to ALINE,  but only horizontal lines can be  drawn.
           x1  and x2 contain the x coordinates of the line start  and
           end points and y the common y coordinate.  f is the  colour
           (0-15).  m  is the graphic mode.  addr is the address of  a
           block of memory which contains bit information for  several
           line  styles  each of 16 bits.  Which style is used  for  a
           given  line  depends  on  both the  y  coordinate  and  the
           parameter  num_pattern.  They  are ANDed together  and  the
           resulting number used as an index to the style table.


HTAB       Positions  the cursor to the  specified  column.  (Counting
           from 0). See also VTAB


IF
Syntax:    IF condition [ THEN ]
             program block
           ELSE
             program block
           ENDIF
Action:    Divides a program up into different blocks depending
           on how it relates to the 'condition'.

ELSE IF condition
           Enables  nested  IF's  to be more clearly  expressed  in  a
           program.

Example:   'the following code has no ELSE IF's
           DO
             t$=CHR$(INP(2))
             IF t$="l"
               PRINT "Load text"
             ELSE
               IF t$="s"
                 PRINT "Save text"
               ELSE
                 IF t$="e"
                   PRINT "Enter text"
                 ELSE
                    PRINT "unknown command"
                 ENDIF
               ENDIF
             ENDIF
           LOOP

           The use of ELSE IF produces shorter code:

           DO
             t$=CHR$(INP(2))
             IF t$="l"
                 PRINT "Load text"
             ELSE IF t$="s"
                 PRINT "Save text"
             ELSE IF t$="e"
                 PRINT "Enter text"
             ELSE
                 PRINT "unknown command"
             ENDIF
           LOOP


IMP
Syntax:    x IMP y
Action:    The  operator  IMP (implication) corresponds to  a  logical
           consequence.   The   result  is  only  FALSE  if  a   FALSE
           expression follows a TRUE one. The sequence of the argument
           is important.

IMP()
Syntax:    IMP(x,y)
Action:    This  function resets a bit if the appropriate bit in x  is
           set and y is reset, otherwise the bit is set.



INC
Syntax:    INC var
Action:    Increases the value of 'var' by 1. the same as
           var=var+1 but executes aprox 3.5 times faster



INFOW
Syntax:    INFOW n,"string$"
Action:    Allocates the (NEW) information line to the window with the
           number 'n'.If the string is empty then the line is removed
           altogether. As the info line cannot be switched off and on
           when the window is opened, infow has to be used in
           front of OPENW when an information line is required.
           If the command INFOW,n,"" is used ("" = null string)
           before OPENW then the window will have no info line.


INKEY$
Syntax:    INKEY$
Action:    Reads a character from the keyboard.
           This function returns a string which is 2, 1 or 0
           characters long.
           Normal keys, return the ASCII code.
           Function keys, HELP, UNDO etc. return two characters:
           The ASCII code zero and then the key code.

Example:
           DO
               t$=INKEY$
               IF t$<>""
                   IF LEN(t$)=1
                      PRINT "Character: ";t$,"ASCII code:";ASC(t$)
                   ELSE
                      PRINT "CHR$(0)+Scan code ";CVI(t$)
                   ENDIF
               ENDIF
           LOOP


INLINE
Syntax:    INLINE var,length
Action:    Reserves an area of memory within a program.
           var is any integer variable
           length is how much memory to reserve, less than 32700 bytes
           The  reserved area always starts at an even address and  is
           initially filled with zeros.  When implementing INLINE this
           address  is written to the integer variable adr.  When  the
           program is loaded or saved, the reserved area is also.

           Placing  the  cursor  on the line  containing  the  command
           INLINE  and  pressing  the HELP key causes a  new  menu  to
           appear with the entries: LOAD SAVE DUMP CLEAR. Load is used
           to  load a machine code program or data into  the  reserved
           area,  save  saves  the  reserved  area  to  disk  (default
           filename extension .INL).  DUMP printsout the reserved area
           in hex to the printer and CLEAR clears the araea of memory.

INP    INP&(#)   INP%(#)
OUT    OUT&      OUT%
Syntax:    INP(#n)
           OUT #n,a[,b,c...]
Action:    Reads one byte from a file previously opened with OPEN.
           Similarly  OUT#n  sends a byte to  a  file.  The  numerical
           expression n is the channel number under which the  channel
           was opened.
           INP  and  OUT without the # can be used  for  communicating
           with the screen,  keyboard etc. eg INP(2) takes a character
           from the keyboard.
           These  functions cater for 16 and 32 bit input and  output.

Example:   a%=CVL(INPUT$(4,#1)) is replaced by a%=INP%(#1)


INP(n)
INP?(n)
OUT[#]n,a[,b..]
OUT?(n)

INP        reads  a  byte  from a  peripheral  device.  The  numerical
           expression  n can accept values 0-5 (see table  below),  or
           contains a channel number(#n). The command OUT sends a byte
           to a peripheral device. You can send several bytes with one
           OUT command.
           INP?  and  OUT?  determine the input or output status of  a
           device. TRUE(-1) is device is ready ortherwise FALSE(0).
           n        Device
           0   LST: (list)             Printer
           1   AUX: (Auxiliary)        RS232
           2   CON: (Console)          Keyboard/screen
           3   MID: (MIDI)             MIDI Interface
           4   IKB: (Intelligent kbd)  Keyboard processor
           5   VID: (Video)            Screen


INPAUX$
INPMID$
           Using these two commands,  data can be read from the serial
           and MIDI interfaces.
Example:
           DO
             PRINT INPAUX$;
           LOOP



INPUT
Syntax:    INPUT ["text",]x{,y,...]
           INPUT ["text";]x[,y,...]
Action:    Allows entry of data during program execution.
           If "text" is given, then a string prompt is displayed.
Example:
           INPUT a$
           INPUT "",b$
           INPUT "enter two numbers: ";x,y


INPUT$
Syntax:    INPUT$(count[,#n]))
Action:    Reads 'count' characters from the keyboard and assigns them
           to  a  string.  Optionally,  if  the channel  number  n  is
           specified,  the  characters are read in from  a  previously
           OPENed channel.


INPUT #n,var1[,var2,var3,...]
LINE INPUT #n,a1$[,a2$,a3$,...]

           These  commands  make  it  possible to  take  data  from  a
           previously OPENed device.  Individual variables or variable
           lists  (where  the  vars are separated by  commas)  can  be
           input.


INSERT
Syntax:    INSERT x(i)=y
Action:    Inserts  an  element  into  an  array.  The  value  of  the
           expression  y  is  inserted into  the  position  x(i).  All
           elements of the array are shifted up by one  position,  and
           the last element lost. See also DELETE.



INSTR
Syntax:    INSTR([n,]a$,b$)      OR       INSTR(a$,b$[,n])
Action:    Searches to see if b$ is present in a$ and returns
           its position.
           'n' is a numeric expression indicating the position in a$
           at which the search is to begin.  If 'n' is not given
           the search begins at the first character of A$.
           If b$ is found in a$ the start position is returned.



INT
Syntax:    INT(x)
Action:    Determines the largest integer that is less than or
           equal to 'x'.



INTIN      Address  of the VDI integer input block.  Also works  with
           index INTIN(2).

INTOUT     Address  of the VDI integer output block.  Also works  with
           index INTOUT(2).



INT{x}     Reads/writes a 2 byte signed integer from/to address x.
           (See also BYTE{},  CARD{},  LONG{},  {}, FLOAT{}, SINGLE{},
           DOUBLE{}, CHAR{} ).


KEYDEF
Syntax:    KEYDEF n,s$
Action:    Assign a string to a Function Key.  The number n (1-20)  is
           the  function  key (for 11 and above use shift  +  function
           key).  The  string is any string.  Whilst using  the  Basic
           Editor,   you  must  also  hold  down  the  Alternate  key,
           otherwise the normal menu commands would not work!



KEYGET n
KEYLOOK n
KEYTEST n

           KEYTEST is simialr to INKEY$ and reads a character from the
           keyboard. If no key was pressed since the last input (apart
           from Alternate,  Control, Shift and Caps Lock) the returned
           value is zero,  otherwise its value corresponds to the  key
           in the fashion shown below for KEYGET.

           KEYGET  waits  for a key to be pressed and then  returns  a
           long word value corresponding to the key.  This 32 bit word
           is constructed as follows:
           Bits 0-8    the ASCII code
           Bits 8-15   Zero
           Bits 16-23  the scan code
           Bits 24-31  status of Shift,  Control, Alternate, Caps lock
           as follows:
           Bit  Key
           24   Right shift
           25   Left shift
           26   Control
           27   Alternate
           28   Caps Lock

           KEYLOOK  allows  a character to be read from  the  keyboard
           buffer,  without  changing the buffer's contents,  as  with
           KEYGET or INKEY$.


KEYPAD n   Sets  the  usage of the  numerical  keypad.  The  numerical
           expression n is evaluated bit by bit and has the  following
           meaning:
           Bit Meaning             0              1
           0   NUMLOCK             On             Off
           1   NUMLOCK             Not Switchable Switchable
           2   CTRL-KEYPAD         Normal         Cursor
           3   ALT_KEYPAD          Normal         ASCII
           4   KEYDEF without ALT  Off            On
           5   KEYDEF with ALT     Off            On

           With  bit 0 set the keypad will act as a 'PC'  keypad  with
           numlock off ie. it responds with cursor movements.

           With  bit 1 set the 'PC' numlock mode can be  toggled  with
           Alternate and '-', otherwise it can't.

           With  bit 2 set,  numlock is effecively switched off  while
           the  Control  key  is held down.  Thus  Control-4  (on  the
           keypad) produces cursor movements.

           With bit 3 set ASCII values for characters can be typed  in
           with the Alternate key held down.  When ALT is released the
           character appears.

           With bit 4 set,  the character strings assigned with KEYDEF
           to  the function keys are output when the key  is  pressed.
           With bit 5 set, the Alternate key must aslo be held down.

           The deafult when the ST is turned on is KEYPAD 0.  with GFA
           Basic in operation it is 46.



KEYPRESS n
           This  simulates the pressing of a key.  The character  with
           the  ASCII  code contained in the lowest 8 bits of  'n'  is
           added  to the keyboard buffer.  Additionally the status  of
           the Shift,  Control and Alternate keys may be passed in the
           high  order bits as defined in KEYGET.  If the  ASCII  code
           given is zero, a scan code may be passed in bits 16-23.
Example:
           KEYPRESS &H3B0000 presses F1.

Example:
           FOR i&=65 TO 90                   ! Simulates the pressing
             KEYPRESS i&                     ! of keys A-Z
           NEXT i&
           KEYPRESS 13                       !followed by Carriage Ret
           INPUT a$                          !Characters are taken up
           '                                 !to  the first CR.
           PRINT a$



KILL
Syntax:    KILL "filespec"
Action:    Deletes a file off disk (only one at a time).



L:         Enable  the passing of numerical expressions  to  Operating
           system functions or to machine code routines.  L: is a long
           word.

Example:   ~XBIOS(5,L:log_base%,L:phys_base%,-1)


LEFT$
Syntax:    LEFT$(a$[,x])
Action:    Returns the first [or first 'x'] character[s] of a string.



LEN
Syntax:    LEN(x$)
Action:    Returns the length of a string.



LET
Syntax:    [LET] var=expression
Action:    Assigns a variable with the value of an expression.



LINE
Syntax:    LINE x,y,xx,yy
Action:    Connects two points ('x,y' & 'xx,yy') with a straight
           line, and is identical to DRAW x,y TO xx,yy.



LINE INPUT
Syntax:    LINE INPUT ["text",]var$ [,var$... ]
           LINE INPUT ["text";]var$ [,var$... ]
Action:    Makes it possible to enter a string during program
           execution.
           This command is the same as INPUT except that a comma
           is taken as part of the entered string and not as a
           separator. Only <RETURN> is regarded as a separator.

LINE INPUT#  See INPUT#



LIST
Syntax:    LIST "filename"
Action:    stores the program currently in memory to disk in ASCII
           format. If the 'filename' is an empty string (eg. "") then
           the listing is shown on the screen.
           In all other cases this command is the same as the editor
           menu option SAVE,A.
           Programs to be joined together using the command MERGE
           must be saved using LIST (or SAVE,A from the menu bar)


LLIST
Syntax:    LLIST
Action:    Prints out the listing of the current program.  The setting
           for the type of output is controlled by the '.' commands in
           the editor.




LOAD
Syntax:    LOAD "filespec"
Action:    Loads a program into memory.



LOC
Syntax:    LOC(#n)
Action:    Returns the location of the file pointer for the file with
           the channel number 'n'
           The location is given in number of bytes from the start of
           the file.



LOCAL
Syntax:    LOCAL var [ ,var.... ]
Action:    Declares 'var' to be a local variable.



LOCATE
Syntax:    LOCATE row,column
Action:    Positions the cursor to the specified location.



LOF
Syntax:    LOF(#n)
Action:    Returns length of file OPENed for channel number 'n'.



LOG  LOG10
Syntax:    LOG(x)
           LOG10(x)
Action:    Determines the natural logarithm (log) or the logarithm
           base 10 (log10) of 'x'.



LONG{x}    Reads/writes a 4 byte integer from/to address x.
or         (See  also  BYTE{},   CARD{},   INT{},  FLOAT{},  SINGLE{},
{x}        DOUBLE{}, CHAR{} ).


LOOP       See DO

LOOP UNTIL condition
LOOP WHILE condition
           The  commands DO and LOOP can be extended using  UNTIL  and
           WHILE. LOOP WHILE causes the program to jump back to the DO
           command  as  long  as the condition  is  true.  LOOP  UNTIL
           requires the condition to be false to cause the loop back.



LPEEK(x)   Reads a 4 byte integer from address x. (In supervisor mode)


LPENX      For the STE. Returns the x coordinate of a light pen.
LPENY      For the STE. Returns the y coordinate of a light pen.



LPOKE n,x  Writes a 4 byte ineger 'x' to address n.  Not in supervisor
           mode. (Add an 'S' to do in super mode ie. SLPOKE n,x).



LPOS
Syntax:    LPOS(n)
Action:    Returns the column in which the printer head (in the printer
           buffer) is located.


LPRINT
Syntax:    LPRINT [expressions [,][;][']]
Action:    prints data on the printer.
           'expression' is any number of expressions separated by
           commas or semicolons or apostrophes. If none of these is
           given a semicolon is assumed.


LSET
Syntax:    LSET var=string
Action:    Puts the 'string' in the string variable 'var'    justified
           to the left.


L~A        Returns the base address of the LINE-A variables.

MALLOC(x)  Allocates an area of memory.  (GEMDOS 72) If x is -1,  then
           the  function  returns the largest contiguous  free  memory
           block.  If x is positive, then MALLOC reserves that area of
           memory and returns its base address.  If 0 is returned then
           there was a fault with the allocation.
           See also RESERVE, MFREE, MSHRINK.



The following 33 commands are for the handling of MATRIXES


MAT ADD
MAT ADD a(),b()
MAT ADD a(),x
MAT ADD a()=b()+c()
MAT BASE
MAT CLR a()
MAT CPY
MAT CPY a([i,j])=b([k,l])[,h,w]
MAT DET x=a([i,j])[,n]
MAT INPUT #i,a()
MAT INV a()=b()
MAT MUL
MAT MUL a(),x
MAT MUL a()=b()*c()
MAT MUL x=a()*b()
MAT MUL x=a()*b()*c()
MAT NORM a(),0
MAT NORM a(),1
MAT ONE a()
MAT PRINT
MAT PRINT [#i]a[,g,n]
MAT QDET x=a([i,j])[,n]
MAT RANG x=a([i,j])[,n]
MAT READ
MAT READ a()
MAT SET a()=x
MAT SUB
MAT SUB a(),b()
MAT SUB a(),x
MAT SUB a()=b()-c()
MAT TRANS a()[=b()]
MAT XCPY
MAT XCPY a([i,j])=b([k,l])[,h,w]

Linear operations with vectors and matrices.
All THE  MAT   functions described relate only to one and/or two-
dimensional fields with floating point variables.

System commands

MAT BASE 0
MAT BASE 1

The MAT BASE command can only sensibly be used when OPTION BASE 0
has been activated.  In this case,  MAT BASE 1 can be used to set
the offset for the start of the row and column indexing of one or
two-dimensional fields with floating point variables to 1 for the
matrix operations. MAT BASE 0 resets this offset to 0 after a MAT
BASE 1.

The setting made with MAT BASE n affects the following commands

MAT READ
MAT PRINT
MAT CPY
MAT XCPY
MAT ADD
MAT SUB
MAT MUL

The default is MAT BASE 1.

Generating commands

MAT CLR a()
MAT SET a()=x
MAT ONE a()

a: Name of field with numeric variables
x: aexp

MAT CLR a() corresponds to an ARRAYFILL a(),0,  i.e.  the command
sets all elements in the field (matrix or vector) a() to a  value
of 0.

MAT SET a()=x corresponds to an ARRAYFILL a(),x, i.e. the command
sets  all  elements in the field a() (matrix or  vector)  to  the
value x.


MAT ONE a() generates from a square matrix a() a uniform  matrix,
i.e.  a square matrix in which elements  a(1,1),a(2,2),...,a(n.n)
are all equally 1 and all other elements equally 0.

Write and Read commands

MAT READ a()
MAT PRINT [#i]a[,g,n]
MAT INPUT #i,a()

i,g,n:  iexp
a:      Name of field with numerical variables

MAT READ a() reads a previously dimensioned matrix or vector from
DATA rows.

MAT  PRINT [#i,]a()[,g,n] outputs a matrix or a  vector.  Vectors
are  output on one row,  the elements being separated by  commas.
With matrix, each row is followed by a rowfeed.

The output can optionally be redirected with #i, as with PRINT.

If  g  and n are specified,  the numbers are  formatted  as  with
STR$(x,g,n).


MAT  INPUT #1,a() reads a matrix or vector from a file  in  ASCII
format  (the format being the reverse of MAT  PRINT,  commas  and
rowfeeds may be varied as with INPUT #).

Copy and Transposition commands

MAT CPY a([i,j])=b([k,l])[,h,w]
MAT XCPY a([i,j])=b([k,l])[,h,w]
MAT TRANS a()[=b()]

a,b:    Name of fields with numerical variables
i,j,k,l,h,w:    iexp

MAT  CPY  a([i,j])=b([k,l])[,h,w] copies h rows with  w  elements
each  from  matrix  b to the row and column offset  of  matrix  a
defined by i,j, starting from the row and column offset of matrix
b defined by l,k.


Special cases

MAT  COPY a()=b() copies the complete matrix b into matrix  a  if
the matrix are of the same order.

Only those elements are copied in this process for which  identi-
cal  indices  are given in both the source  and  the  destination
matrix.


MAT  COPY a(i,j)=b() copies matrix b,  starting from the row  and
column offset defined by MAT BASE,  to the row and column  offset
of  matrix a defined by i,j.  Only those elements are copied  for
which  identical  indices are given in both the  source  and  the
destination matrix.


MAT  COPY a()=b(i,j) copies matrix b,  starting from the row  and
column  offset defined by i,j,  to the offset of matrix a defined
by MAT BASE.  Only those elements are copied for which  identical
indices are given in both the source and the destination matrix.


MAT COPY a(i,j)=b(k,l) copies matrix b, starting from the row and
column offset defined by k,l, to the offset i,j of matrix a. Only
those  elements are copied for which identical indices are  given
in both the source and the destination matrix.


MAT  COPY  a()=b() copies h rows with w elements  each  from  the
matrix b,  starting from the row and column offset defined by MAT
BASE,  the row and column offset of matrix a defined by MAT BASE.
Only  those elements are copied for which identical  indices  are
given in both the source and the destination matrix.


MAT  XCPY  a([i,j])=b([k,l])[,h,w] works basically  in  the  same
manner as MAT CPY a([i,j])=b([k,l])[,h,w],  except that matrix  b
is being transposed while being copied to matrix a, i.e. the rows
and columns of matrix b are swapped while it is copied to  matrix
a.  Array b remains unchanged,  however.  Only those elements are
copied  for which identical indices are given in both the  source
and the destination matrix.


Further special cases

As with MAT CPY a(i,j)=b(k,l),w,h.

If  MAT CPY or MAT XCPY are applied to vectors,  j and l  may  be
ignored.  Following a DIM a(n),b(m),  a() and b() are interpreted
as row vectors, i.e. as matrix of the (1,n) or (1,m) types.

For  a  and  b to be treated as  column  vectors,  they  must  be
dimensioned  as  matrix  of the (n,1)  or  (m,1)  type,  ie.  DIM
a(n,1),b(n,1).

If  both  vectors are of the same order (both are row  or  column
vectors),  MAT  CPY  must be used.  Irrespective of the  type  of
vectors a and b, MAT CPY always treats both vectors syntactically
as column vectors,  so that the correct syntax to be used for MAT
CPY is always

MAT CPY a(n,1)=b(m,1)!
MAT CPY a(3,1)=b(1,1) ! interprets a() and b() as column vectors

For MAT XCPY,  one of the two vectors a and b must be  explicitly
dimensioned as a row vector,  the other as a column  vector.

Since MAT XCPY first transposes the second vector before  copying
it to the first.  For this reason,  MAT XCPY can only be used for
DIM  a(1,n),b(m,1):  a()=row vector,  b()=column vector  and  DIM
a(n,1),b(1,m): a()=column vector, b()=row vector.

Optionally,  the parameters h and w can also be used when copying
vectors   with  MAT  CPY or  MAT  XCPY.  However,  the  following
applies:  with MAT CPY, only the h parameter is used for w=>1. No
copying takes place with w=0.

With MAT XCPY, only h is used for w=>1 if b is a column vector to
be copied into a row vector after transposition. No copying takes
place when w=0.  On the other hand,  only w is used for h=>1 if b
is  a row vector which is to be copied to a column  vector  after
transposition. In this case, no copying takes place if h=0.

MAT TRANS a()=b() copies the transposed from matrix b to matrix a
if a and b are dimensioned accordingly,  i.e.  the number of rows
from  a must correspond to the number of columns in  b,  and  the
number of columns from a to the number of rows of n.

In the case of a square matrix,  i.e.  one with equal numbers  of
rows and columns,  MAT TRANS a() may be used.  This command swaps
the  rows  and  columns of matrix a and writes  the  matrix  thus
changed back to a.

(The original matrix is lost in the process (but can be  restored
with another MAT TRANS a()).

Operation commands

MAT ADD a()=b()+c()
MAT ADD a(),b()
MAT ADD a(),x

MAT SUB a()=b()-c()
MAT SUB a(),b()
MAT SUB a(),x

MAT MUL a()=b()*c()
MAT MUL x=a()*b()
MAT MUL x=a()*b()*c()
MAT MUL a(),x

MAT NORM a(),0
MAT NORM a(),1

MAT DET x=a([i,j])[,n]
MAT QDET x=a([i,j])[,n]
MAT RANG x=a([i,j])[,n]
MAT INV a()=b()

a,b,c: Names of numerical floating point fields
x:     aexp; scalar value
i.j,n: aexp

MAT  ADD a()=b()+c() is only defined for matrix (vectors) of  the
same order,  e.g. DIM a(n,m),b(m,m),c(n,m) or DIM a(n),b(n),c(n).
Array c is added to matrix b,  element by element, and the result
is written to matrix a.

MAT ADD a(),b() is only defined for matrix (vectors) of the  same
order,  e.g. DIM a(n,m),b(n.m) or DIM a(n),b(n). Array b is added
to  matrix a,  element by element,  and the result is written  to
matrix a. The original matrix a is lost in the process.

MAT  ADD a(),x is defined for all  matrix  (vectors).  Here,  the
scalar x is added to matrix a, element by element, and the result
is  written  to matrix a.  The original matrix a is lost  in  the
process.

MAT  SUB a()=b()+c() is only defined for matrix (vectors) of  the
same order,  e.g. DIM a(n,m),b(n,m),c(n,m) or DIM a(n),b(n),c(n).
Array c is subtracted from matrix b, element by element, and the
result is written to matrix a.

MAT SUB a(),b() is only defined for matrix (vectors) of the same
order,  e.g.  DIM  a(n,m),b(n,m)  or DIM a(n),b(n).  Array  b  is
subtracted  from  matrix a,  element by element,  and  the  result
written to matrix a. The original matrix a is lost in the process.

MAT  SUB a(),x is defined for all  matrix  (vectors).  Here,  the
scalar x is subtracted from matrix x, element by element, and the
result is written to matrix a.  The original matrix a is lost  in
the process.

MAT  MUL  a()=b()*c() is defined for matrix of  an  "appropriate"
order. Arrays  b and c are multiplied with each other. The result
of this multiplication is written to matrix a.  In order for  the
result  to be defined,  the matrix on the left (matrix b in  this
case)  must have the same number of columns as the matrix on  the
right (c in this case) has rows. Array a, in this case, must have
as many rows as b and as many columns as c.

Arrays are multiplied as "row by column",  i.e. element a(i.j) is
obtained by multiplying the elements in the ith row of matrix   b
with  the  elements in the jth column of  matrix  c,  element  by
element, and then adding up the individual products.

With  vectors instead of matrix,  MAT MUL a()=b()*c() results  in
the dyadic (or external) product of two vectors.

MAT  MUL  x=a()*b()  is only defined for vectors  with  an  equal
number of elements.  The result x is the scalar product (the  so-
called interior product) of vectors a and b.  The scalar  product
of   two   vectors  is  defined  as  the  sum   of   n   products
a(i)*b(i),i=1,...,n.

MAT  MUL x=a()*b()*c() is defined for  qualified Vectors a and  c
as  well  as qualified Matrix b().

MAT  NORM  a(),0  or MAT NORM a(),1 are defined  for  matrix  and
vectors.  MAT NORM a(),0 normalises a matrix (a vector) by  rows,
MAT NORM a(),1 by columns.  This means that after a normalisation
by  rows (by columns) the sum of the squares of all  elements  in
each row (column) is identical at 1.

MAT  DET x=a([i,j])[,n] calculates the determinants of  a  square
matrix of the (n,n) type.  The row and column offsets are  preset
to  a(0,0)  or a(1,1),  depending on MAT BASE 0 or  MAT  BASE  1,
assuming  that  OPTION BASE 1 is enabled.  It is  also  possible,
however, to calculate the determinant of a square part matrix. To
do this, the row and column offsets of a() must be specified as i
and j, and the number of elements in the part matrix as n. A part
matrix of the (n,n) type is then created internally starting from
the "position" ith row, jth column.

MAT  QDET  x=a([i,j])[,n]  works in the same manner  as  MAT  DET
x = a([i,j])[,n],  except  that it has been optimised  for  speed
rather  than accuracy.  Both will normally produce identical  re-
sults.  With "critical" matrix,  whose determinant is close to 0,
you should always use MAT DET, though.


MAT RANG x=a([i,j])[,n] outputs the rank of a square  matrix.  As
with  MAT  DET or MAT QDET,  you can select any  row  and  column
offset.  The  number  of  elements in the  part  matrix  must  be
specified with n.  This creates  a part matrix of the (n,n)  type
internally, starting from the "position ith row, jth column.


MAT  INV  b()=a() is used to determine the inverses of  a  square
matrix. The inverse of matrix a() is written to matrix b(), hence
b() must be of the same type as a().



MAX
Syntax:    MAX(x [,y,z,...])  or  MAX(a$[,y$,z$....])
Action:    Returns the greatest value (or largest string) from
           a list of expressions.


MENU(x)    Returns the information about an event in the variable
           'x' (-2 to 15). In the case where an item in a menu is
           selected, the index of that item is found in MENU(0).
           MENU(-2) is the address of the message buffer.
           MENU(-1) is the address of the menu object tree.
           The  Message Buffer lies in the the variables  MENU(1)
           to MENU(8) and the AES Integer Output Block in MENU(9)
           to MENU(15).
           The Identification number of the event is in  MENU(1).
           The  other  elements of the  message  bufffer  contain
           various  values,  depending on the type of event  that
           occured.

           MENU(1)=10         A Menu Item was selected.
               MENU(0)        Menu item index in the item list
               MENU(4)        Object number of the menu title
               MENU(5)        Object  number of the  chosen  menu
                              item

           MENU(1)=20         A window redraw is required
               MENU(4)        ID number (handle) of the window
               MENU(5),(6)    Coordinates  of top left corner  of
                              the window
               MENU(7),(8)    Width & height of the window area

           MENU(1)=21         A window was clicked (activated)
               MENU(4)        ID number (handle) of the window

           MENU(1)=22         The  close  box  of  a  window  was
                              clicked on
               MENU(4)        ID number (handle) of the window

           MENU(1)=23         The full box was clicked on
               MENU(4)        ID number (handle) of the window

           MENU(1)=24         One of the four arrow boxes,  or  a
                              slider  bar area was  clciked.  The
                              movement of a slider is detected as
                              below,  MENU(1)=24  only  when  the
                              grey area is clicked on.
               MENU(4)        ID number (handle) of the window
               MENU(5)        The  area  of the window  that  was
                              clicked:
                              0: Above the vertical slider
                              1: Below  "     "       "
                              2: Up arrow
                              3: Down arrow
                              4: Left of the horizontal slider
                              5: Right "  "      "        "
                              6: Left arrow
                              7: Right arrow

           MENU(1)=25         The horizontal slider was moved
               MENU(4)        ID number (handle) of the window
               MENU(5)        Position of the moved slider (1  to
                              1000)

           MENU(1)=26         The vertical slider was moved
               MENU(4)        ID number (handle) of the window
               MENU(5)        Position of the moved slider (1  to
                              1000)

           MENU(1)=27         The size of the window was  changed
                              (using the size box)
               MENU(4)        ID number (handle) of the window
               MENU(5),(6)    New x and y coordinates of top left
               MENU(7),(8)    New width & height

           MENU(1)=28         The window's position was changed
               same parameters as above

           MENU(1)=29         A new GEM window was activated.
               MENU(4)        ID number (handle) of the window

           MENU(1)=40         An  Accessory  was  selected.  This
                              value  can only be received  by  an
                              accessory,  which should chech  the
                              value  in MENU(5) to see if  it  is
                              that one being referred to.
               MENU(5)        ID of the accessory

           MENU(1)=41         An accessory was closed. This value
                              can   only  be  received  from   an
                              accessory.
               MENU(5)        ID of the accessory

           The varaible MENU(9) contains bit information on which
           kind  of  event  has occurred.  If  the  bit  for  the
           appropriate  event is set,  the variables  MENU(9)  to
           MENU(15)  and  GINTOUT(0) to GINTOUT(6)  will  contain
           information as follows:
               Bit 0  Keyboard
               Bit 1  Mouse button
               Bit 2  Mouse has entered/left rectangle 1
               Bit 3  Mouse has entered/left rectangle 2
               Bit 4  A message arrived in the message buffer
               Bit 5  Timer event


           MENU(10) x position of mouse when event terminated
           MENU(11) y position of mouse when event terminated
           MENU(12) Mouse buttons pressed:
                    0 = none
                    1 = left
                    2 = right
                    3 = both buttons
               See also ON MENU BUTTON

           MENU(13) supplies  the  status of the  keyboard  shift
                    keys in a bit pattern:
                    Bit 0 = right shift
                    Bit 1 = left shift
                    Bit 2 = control
                    Bit 3 = alternate
               See also ON MENU KEY

           MENU(14) Gives  information about a pressed  key.  The
                    low order byte contains the ASCII  code,  and
                    the high order byte, the keyboard scan code

           MENU(15) Returns  the  number  of  mouse  clicks  that
                    caused the event


MENU
Syntax:    MENU m$()
Action:    Displays  a menu bar.  The string array m$()  contains
           the   headings,   entries  and  reserved   space   for
           accessories  for the menu bar.  The  following  format
           must be adhered to:
           m$(0)        Name of the accessory menu heading
           m$(1)        Name of the first entry in the first menu
           m$(2)        A line of minus signs
           m$(3)-m$(8)  Reserved  space  for  accessories.  These
                        elements need only be 1 character long.
           m$(9)        An empty string,  which marks the end  of
                        the first menu.
           All further menu entries have the following format:
           1. Heading of the menu
           2. List of menu entries
           3. An empty string which marks the end of the menu.

           After the last entry, a further empty string signifies
           the end of the entire pull down menu.

           eg:

DIM entry$(20)
DATA "  Desk  ","  Test  "
DATA ----------,1,2,3,4,5,6,""
DATA "  File  ","  Load  ","  Save  "
DATA --------,"  Quit  ",""
DATA "  Titles  ","  Entry 1  ","  Entry 2  ",""
DATA End
i%=-1
REPEAT
  INC i%
  READ entry$(i%)
UNTIL entry$(i%)="End"
entry$(i%)=""
MENU entry$()
ON MENU GOSUB evaluate
'
REPEAT
  ON MENU
UNTIL MOUSEK AND 2
'
PROCEDURE evaluate
  MENU OFF
  ' MENU(0) contains array index of selected item
  m%=MENU(0)
  PRINT entry$(m%)
  '
  ALERT 0,"Tick before item ?",0,"YES|NO",a%
  IF a%=1
    MENU m%,1
  ELSE
    MENU m%,0
  ENDIF
  '
  ALERT 0,"Lightened characters | (Not selectable)",0,"YES|NO",a%
  IF a%=1
    MENU m%,2
  ELSE
    MENU m%,3
  ENDIF
RETURN


MENU x,y
Action:    The  x-th  entry of a menu can be  given  certain  (y)
           attributes:
               0  remove tick from in front of menu entry
               1  install tick     "    "    "   "    "
               2  make menu entry non selectable (light text)
               3  make menu entry selectable (normal text)
               See MENU example.



MENU KILL
Action:    Deactivates  a menu,  but does not remove it from  the
           screen. Also turns off the ON MENU GOSUB options.

MENU OFF
Action:    Returns  a menu title to 'normal' display.  (After  an
           item  is  chosen from a menu,  the title is  shown  in
           reverse video).


MENU_BAR
Syntax:    a%=MENU_BAR(tree%,flag)
Action:    Displays/erases a menu bar (from a resource file)
           Returns 0 if an error occurred.
           tree = address of the menu object tree
           flag - 1 display bar
                - 2 erase bar
           See also MENU x$ and MENU KILL

MENU_ICHECK
Syntax:    a%=MENU_ICHECK(tree,item,flag)
Action:    Deletes/displays a tick against a menu item.
           tree = address of the menu object tree
           item = object number of the menu item
           flag - 1 delete tick
                - 2 display tick
           See also MENU x,0 and MENU x,1



MENU_IENABLE
Syntax:    a%=MENU_IENABLE(tree,item,flag)
Action:    Enables/disables a menu entry.
           tree = address of the menu object tree
           item = object number of the menu entry
           flag - 1 disable
                - 2 enable
           See also MENU x,2 and MENU x,3


MENU_REGISTER
Syntax:    a%=MENU_REGISTER(ap_id,m_text$)
Action:    Give a desk accessory a name,  and insert it into  the
           accessory menu entries.  (provided the number of  Accs
           is less than 6).
           Returns  the  object number of  the  appropriate  menu
           item:
           0-5 for a valid result
           -1  no more entries possible
           ap_id   = ID number of the accessory
           m_text$ = name for the Accessory



MENU_TEXT
Syntax:    a%=MENU_TEXT(tree,item,new_text$)
Action:    Changes the text of a menu item.
           Returns 0 on error.
           tree = address of the menu object tree
           item = object number of the menu item
           new_text$  the  new text for the menu entry  (may  not
                      exceed the old text length)


MENU_TNORMAL
Syntax:    a%=MENU_TNORMAL(tree,title,flag)
Action:    Switches the menu title to normal/inverse video.
           Returns 0 on error.
           tree = address of the menu object tree
           item = object number of the menu item
           flag - 1 inverse video
                - 2 normal video
           See MENU OFF


MFREE
Syntax:    a%=MFREE(y)
Action:    (GEMDOS  73)  Releases the storage  location  reserved
           with MALLOC.  The parameter 'y' specifies the start of
           the  area of memory to be released.  Returns 0  if  no
           error occurred, otherwise negative result.



MID$
Syntax:    MID$(a$,x[,y]) (as a function)
Action:    Returns 'y' characters in a string from the positon 'x'
           of the string 'a$'.  If x is larger than the length of
           a$,  then a null string is returned.  If y is omitted,
           then the function returns the whole of the string from
           position x onwards.


MID$
Syntax:    MID$(a$,x[,y]) (as a command)
Action:    MID$ used as a command,  makes it possible to  replace
           part   of  a  string  variable  a$  with  the   string
           expression  b$.  So with  MID$(a$,x,y)=b$,  characters
           from b$ will overwrite those in a$, starting at the x-
           th postion of a$.  The optional parameter y determines
           how many characters of b$ are used.  If y is  omitted,
           then as many characters as possible of a$ are replaced
           with those from b$.  The length of a$ is unchanged, so
           that  no charatcers will be written beyond the end  of
           a$
           eg:
           a$="GFA SYSTEMTECHNIK"
           MID$(a$,5)="BASIC "
           would result in a$ being "GFA BASIC TECHNIK"



MIN
Syntax:    MIN(expression [ ,expression... ])
Action:    Returns the smallest value (or smallest string) from
           a list of expressions.



MKDIR
Syntax:    MKDIR "directory name"
Action:    Creates a new directory.
           'directory name' is the name of the new directory.




MKI$ MKL$ MKS$ MKF$ MKD$
Syntax:    MKI$(N)
           MKL$(N)
           MKS$(N)
           MKF$(N)
           MKD$(N)
Action:    Transforms a number into a character string.
           MKI$ 16-bit number into a 2-byte string.
           MKL$ 32-bit number into a 4-byte string.
           MKS$ a number into an atari basic 4-byte format.
           MKF$ a number into GFA Basics own 6-byte format.
           MKD$ a number into a Mbasic compatible 8-byte format.

           Every number that is to be stored in a random access
           file must first be transformed with on of the above
           functions.
           The example above shows that GFA Basic stores numbers
           internally in the 6-byte format which can also be
           created using the MKF$ function.
           See also CVI,CVL,CVD,CVF



MOD
Syntax:    a=x MOD y    or   a=MOD(x,y)
Action:    Produces the remainder of the division of x by y.
           The   command   in  brackets   operates   in   integer
           arithmetic.



MODE
Syntax:    MODE n
Action:    With MODE the representation of decimal point and  the
           'thousands comma' are interpreted by PRINT USING  (and
           also by STR$ with 3 parameters).
           Also selects the format of date representation used by
           DATE$, SETTIME, and FILES.

           MODE  USING     DATE$
           0     #,###.##  16.05.1988
           1     #,###.##  05/16/1988
           2     #.###,##  16.05.1988
           3     #.###,##  05/16/1988




MONITOR
Syntax:    MONITOR [x]
Action:    Calls a monitor resident in memory.  This  instruction
           causes  an illegal instruction vector.  (address  16).
           The parameter x is passed via the register D0.



MOUSEX
MOUSEY
MOUSEK
MOUSE mx,my,mk
Syntax:    MOUSE x,y,k
           x=MOUSEX
           y=MOUSEY
           k=MOUSEK
Action:    Determines the mouse position (x,y) and the status of
           the mouse buttons:
           k=0 no buttons pressed
           k=1 left button
           k=2 right button
           k=3 both buttons


MSHRINK
Syntax:    a%=MSHRINK(y,z)
Action:    (GEMDOS  74)  Reduces  the  size  of  a  storage  area
           previously  allocated  with MALLOC.  y  specifies  the
           address of the area,z gives the required size.
           Returns 0 if no error,  -40 if incorrect address, or -
           67 if size wrong.
           See also RESERVE MALLOC MFREE



MUL
Syntax:    MUL var,n
Action:    Multiplies the value 'var' by 'n'.
           same as var=var*n but executes 30% faster.

MUL()      Same as for MUL. but integers only.



MW_OUT
Syntax:    MWOUT mask,data
           This  command  controls the  STE-Internal  Micro-Wire-
           Interface,  and  is  currently  used  for  controlling
           sound.

               MWOUT &H7FF,x

               x=&X10 011 ddd ddd       Set Master Volume
                          000 000       -80 dB
                          010 100       -40 dB
                          101 xxx         0 dB

           The  value of the last 5 Bits is eqivalent to HALF  of
           the volume in dB.

               x=&X10 101 xdd ddd       Set Right Channel Volume
                           00 000       -40 dB
                           01 010       -20 dB
                           10 1xx         0 dB

               x=&X10 100 xdd ddd       Set Right Channel Volume

               The last 4 Bits*2 = dB

               x=&X10 010 xxd ddd       Set Treble
               x=&X10 001 xxd ddd       Set Bass
                            0 000       -12dB
                            0 110       0 dB (flat)
                            1 100       +12 dB

               x=&X10 000 xxx xdd       Set Mix
                               00       -12dB
                               01       Mix GI Sound (normal ST)
                               10       Not Mix
                               11       Reserved

Example: MWOUT &H7FF,&X10000000010 Switches the ST's sound off.



NAME
Syntax:    NAME "oldfile" AS "newfile"
Action:    Renames an existing file. The contents of the file are
           not affected.



NEW
Syntax:    NEW
Action:    Deletes the program currently in memory and clears all
           variables.

NOT
Syntax:    NOT x
Action:    Negates a given logical expression.


The following 19 commands belong to the AES Object library.

OBJC_ADD
Syntax:    a%=OBJC_ADD(tree,parent,child)
Action:    Adds  an object to a given tree and  pointers  between
           the existing objects and the new object are created.
           Returns 0 on error.
           tree     address of the object tree
           parent   object number of the parent object
           child    object number of the child to be added.


OBJC_CHANGE
Syntax:    a%=OBJC_CHANGE(tree,obj,res,cx,cy,cw,ch,new_status,re_draw)
Action:    Changes the status of an object.
           Returns 0 on error.
           tree     address of the object tree
           obj      number of the object to be changed
           res      reserved (always 0)
           cx,cy    coordinates  of top left corner  of  clipping
                    rectangle
           cw,ch    width & height of clipping rectangle
           new_status   new object status
           re_draw  1 = redraw object
                    0 = don't redraw


OBJC_DELETE
Syntax:    a%=OBJC-DELETE(tree,del_obj)
Action:    An  object is deleted from an object tree by  removing
           the  pointers.  The object is still there and  can  be
           restored by repairing the pointers.
           Rteurns 0 on error.
           tree     address of the object tree
           del_obj  Object number of the object to delete.



OBJC_DRAW
Syntax:    a%=OBJC_DRAW(tree,start_obj,depth,cx,cy,cw,ch)
Action:    Draws  whole objects or part of objects on  screen.  A
           clipping rectangle is specified,  to which the drawing
           is limited.
           Returns 0 on error.
           tree     address of the object tree
           start_obj  number of the first object to be drawn
           depth    Number of object levels to be drawn
           cx,cy    coordinates  of top left corner  of  clipping
                    rectangle
           cw,ch    width & height of clipping rectangle


OBJC_EDIT
Syntax:    a%=OBJC_EDIT(tree,obj,char,old_pos,flag,new_pos)
Action:    Allows  input  and  editing in  G_TEXT  and  G_BOXTEXT
           object types.
           Returns 0 on error.
           tree     address of the object tree
           obj      number of the object to be changed
           char     input character (incl. scan code)
           old_pos  current cursor position in input string
           flag     funtion:
                    0 ED_START     -reserved-
                    1 ED_INIT      string is formatted & cursor on
                    2 ED_CHAR      Character processed &  string
                                    redisplayed
                    3 ED_END       Text cursor switched off
           new_pos  returns  new  pos  of  text  cursor  to  this
                    variable.


OBJC_FIND
Syntax:    a%=OBJC_FIND(tree,start_obj,depth,fx,fy)
Action:    Determines  the  object,  if  any,  which  is  at  the
           coordinates specified in fx,fy.
           Returns the object number, or -1 if no object found.
           tree     address of the object tree
           start_obj  number of the object from where to search
           depth    Number of object levels to be searched
           fx       x coordinate (usually MOUSEX)
           fy       y coordinate (usually MOUSEY)


OBJC_OFFSET
Syntax:    a%=OBJC_OFFSET(tree,obj,x_abs,y_abs)
Action:    Calculates  the  absolute screen  coordinates  of  the
           specified object.
           Returns 0 on error.
           tree     address of the object tree
           obj      object number
           x_abs,y_abs  returns  the  x,y  coordinates  to  these
                        variables.



OBJC_ORDER
Syntax:    a%=OBJC_ORDER(tree,obj,new_pos)
Action:    re-positions an object within a tree.
           Returns 0 on error.
           tree     address of the object tree
           obj      object number
           new_pos  new level number



OB_ADR
Syntax:    adr%=OB_ADR(tree,obj)
Action:    Gets the address of an individual object.
           Returns 0 on error.
           tree     address of the object tree
           obj      object number


OB_FLAGS
Syntax:    a%=OB_FLAGS(tree,obj)
Action:    Gets the status of the flags for an object.
           Returns 0 on error.
           tree     address of the object tree
           obj      object number
           OB_FLAGS     Bit No.
           Normal       -
           Selectable   0
           Default      1
           Exit         2
           Editable     3
           Rbutton      4
           Lastob       5
           Touchexit    6
           Hidetree     7
           Indirect     8


OB_H
Syntax:    h%=OB_H(tree,obj)
Action:    Returns the height of an object
           Returns 0 on error.
           tree     address of the object tree
           obj      object number


OB_HEAD
Syntax:    h%=OB_HEAD(tree,obj)
Action:    Points to the object's first child, or -1 if none.


OB_NEXT
Syntax:    n%=OB_NEXT(tree,obj)
Action:    Points to the following object on the same level,  or,
           if it is the last object on that level,  to the parent
           object, or -1 if none.


OB_SPEC
Syntax:    a%=OB_SPEC(tree,obj)
Action:    Returns the address of the the data structure for  the
           object.


OB_STATE
Syntax:    s%=OB_STATE(tree,obj)
Action:    returns the status of an object:
           OB_STATE     Bit No.
           Normal       -
           Selected     0
           Crossed      1
           Checked      2
           Disabled     3
           Outlined     4
           Shadowed     5


OB_TAIL
Syntax:    t%=OB_TAIL(tree,obj)
Action:    Points to the objects last child, or -1 if none.


OB_TYPE
Syntax:    t&=OB_TYPE(tree,obj)
Action:    Returns the type of object specified.


OB_W
Syntax:    w%=OB_W(tree,obj)
Action:    Returns the width of an object


OB_X
OB_Y
Syntax:    x (or y) =OB_X or OB_Y(tree,obj)
Action:    Rteurns   the  relative  coordinates  of  the   object
           relative  to  its parent (or the screen if it  is  the
           parent)


OCT$
Syntax:    OCT$(x[,n])
Action:    Changes the value 'x' into a string containing the
           value of 'x' in octal form (prefix &O),  the  optional
           parameter n, giving the number of characters to print.


ODD
Syntax:    ODD(n)
Action:    Determines whether a number is odd. (see also even)



ON BREAK Syntax:    ON BREAK
           ON BREAK CONT
           ON BREAK GOSUB name
Action:    ON BREAK CONT makes it impossible to stop a program
           by pressing break ( <ALT><SHIFT><CNTRL> ).
           ON BREAK reactivates it.
           ON BREAK GOSUB makes it possible to jump to the procedure
           'name' by the above key combination.


ON ERROR
Syntax:    ON ERROR
           ON ERROR GOSUB name
Action:    Performs the procedure 'name' when an error occurs.
           The program is not interrupted and no error message
           is given.
           See also RESUME


ON...GOSUB
Syntax:    ON x GOSUB proc1,proc2......
Action:    Depending on the result of 'x'  one of several   given
           procedures is processed.
           'proc1' ..  is a list of procedure names separated  by
           commas. The result of 'x' denotes which procedure is
           carried out.
           Eg: If result = 1 then the first procedure in the
           procedure list is processed.
           If result = 2 then the second procedure in the procedure
           list is processed.
           If result = 3 then the third procedure in the procedure
           list is processed and so on.
           If the value is not in the  range then no procedure
           will be executed.



ON MENU
Syntax:    ON MENU[t]
Action:    This  command  handles  EVENTs.   Prior  to  use,  the
           required  action should be specified with an  ON  MENU
           xxx GOSUB command. For constant supervision of events,
           ON MENU is usually found in a loop.
           The parameter t is the time in thousandths of a second
           to elapse before the ON MENU command is terminated.




ON MENU xxx GOSUB
Syntax:    ON MENU BUTTON clicks,but,state GOSUB proc
Action:    Sets up the action to be taken when one or more  mouse
           clicks  are  received.   With  a  subsequent  ON  MENU
           command,  the  named procedure will be branched to  if
           the condition imposed by the parameters are met.
           clicks   -   sets  the maximum number of  clicks  that
                        will generate a response.
           button   -   The expected button combination:
                        0 - any
                        1 - left
                        2 - right
                        3 - both
           state    -   Specifies which button state (up or down)
                        will cause the event. 0 = up, 1 = down
           proc     -   The procedure to branch to.


Syntax:    ON MENU GOSUB proc
Action:    The  procedure  to  which control will  be  passed  on
           selection of  a  menu  entry  is  determined.   If  an
           accessory is currently open, the procedure will not be
           called.
           See also MENU(0)


Syntax:    ON MENU IBOX n,x,y,b,h GOSUB proc
Action:    Monitors  the mouse coordinates,  and branches to  the
           named  procedure  if the mouse  enters Y
           k=MOUSEK
Action:    Determines the mouse position (x,y) and the status of
           the mouse buttons:
           k=0 no buttons pressed
           k=1 left button
           k=2 right button
           k=3 both buttons




Syntax:    ON MENU KEY GOSUB proc
Action:    Monitors the keyboard,  and branches to proc if a  key
           was pressed during an ON MENU loop.
           See MENU(13) & MENU(14) for the keys.



Syntax:    ON MENU MESSAGE GOSUB proc
Action:    Brances  to proc if a message arrives in  the  message
           buffer during an ON MENU loop.
           See MENU(x) for the messages.


Syntax:    ON MENU OBOX n,x,y,w,h GOSUB proc
Action:    Monitors  the mouse coordinates,  and branches to  the
           named  procedure  if the mouse  leaves  a  rectangular
           screen area. It is possible to wait for two such boxes
           to  be left (n can be 1 or 2 ).  x and y are  the  top
           left  coordinates of the rectangle,  w & h  being  its
           width and height.  Continuous monitoring is done  with
           ON MENU.


OPEN
Syntax:    OPEN mode$,#n,name$[,len]
Action:    Opens a data channel to a file or a peripheral device.
           'mode' must always be written in quotes and is one
           of the following :-
           'O' (output) opens a write file creating a new file if
           needed.
           'I' (input) opens a read file.
           'A' (append) enables data to be annexed to an existing
           file.
           'U' (update) read/write, but file must be opened by 'o'
           first.
           'R' stands for random access file.
           Instead  of  a filename,  a periphral  device  can  ne
           specified.  The  expression  'len' is used  only  with
           Random Access mode.
           the following can be used instead of filenames :-
           'CON:'  for the console.
           'LST:'  or 'prn:' for the printer.
           'AUX:'  for the serial interface.
           'MID:'  for midi.
           'VID:'  for the console in transparent mode
                   (commands are produced but not executed).
           'IKB:'  for direct access to the keyboard controller.
           'STD:'. (This is the same as 'Stdin','Stdout' resp. in
           C-programs.) So you can use  a shell to redirect the
           output of a GFA-BASIC program.

           GFABASIC TEST >DUMMY

           This line starts GFA BASIC and the program TEST.PRG
           Any output via 'STD:' is redirected to the file  DUMMY.
           IMPORTANT: CONTROL-C will cause a hang- up when given
           while reading/writing DUMMY. the default for input/output
           is the keyboard/console.
           The  numerical  expression 'n'  contains  the  channel
           number (0-99), and the variable name$, the access path
           and filename.



OPENW
Syntax:    OPENW nr[,x a  rectangular
           screen  area.  It  is possible to wait  for  two  such
           boxes  to be entered (n can be 1 or 2 ).  x and y  are
           the top left coordinates of the rectangle, w & h being
           its  width and height.  Continuous monitoring is  done
           with ON MENU.



OPTION BASE
Syntax:    OPTION BASE 0 (default)
           OPTION BASE 1
Action:    This  command  can determine whether an  array  is  to
           contain a zero element or not. ie. with OPTION BASE 0,
           doing a DIM a%(10) will allow a%(0) to exist.


OR
Syntax:    x OR y
Action:    The  command OR (disjunction) checks whether at  least
           one of two logical expressions x and y is  TRUE.  Only
           if  x  and y are both FALSE will the result  FALSE  be
           produced.


OR()
Syntax:    OR(x,y)
Action:    The  result of OR contains bits set in the  places  in
           which bits are set in either x or y or both.



OTHERWISE  See SELECT



OUT
Syntax:    OUT [#]n,a[,b..]
Action:    Transfers a byte[s] with the value 'a' to a peripheral
           device or file 'n'.
           See OPEN for valid peripherals.
           See also INP

OUT#       See INP#


OUT?
Syntax:    OUT?(n)
Action:    Determines the output status of a periphery.
           This function returns 0 if a character can be output.
           (see also INP?)


PADT(i)
Syntax:    a=PADT(i)
Action:    Reads the paddle buttons on the STE


PADX(i)
PADY(i)
Syntax:    a=PADX(i)  or  PADY(i)
Action:    Reads the x or y position of the paddles on the STE. i
           can be 0 or 1.



PAUSE
Syntax:    PAUSE x
Action:    Interrupts a program for exactly  x/50 seconds.
           See also DELAY.



PBOX
Syntax:    PBOX x,y,x1,y1
Action:    Draws  a filled rectangle with the coordinates of  the
           two opposite corners specified by x,y and x1,y1.
           See also BOX,PRBOX, RBOX.


PCIRCLE
Syntax:    PCIRCLE x,y,r[,w1,w2]
Action:    Draws a filled circle with centre coordinates  at  x,y
           and a radius r.  Additional start and end angles w1 and
           w2 can be specified to draw a circular arc.



PEEK  DPEEK  LPEEK
Syntax:    PEEK(x)
           DPEEK(x)
           LPEEK(x)
Action:    Returns the contents of the memory at address 'x'
           PEEK  returns a 1 byte at address x
           DPEEK  returns a 2 byte number from x and x+1
           LPEEK  returns a 4 byte number from x, x+1, x+2 & x+3
           for DPEEK and LPEEK, 'x' must be an even number.





PELLIPSE
Syntax:    PELLIPSE x,y,rx,ry [,phi0,phi1]
Action:    Draws a filled ellipse at x,y, having 'rx' as length of the
           horizontal axis and 'ry' as length of the vertical axis
           The optional angles 'phi0' & 'phi1' give start and end
           angles in tenths of a degree, to create an elliptical arc.


PI
Syntax:    PI
Action:    Returns the value of PI. The value of PI is
           3.141592653.....etc.



PLOT
Syntax:    PLOT x,y
Action:    Plots a point on the screen coordinates 'x,y'.
           This command is the same as draw x,y.



POINT
Syntax:    POINT x,y
Action:    Checks if a graphic dot (at 'x,y') has been set and
           returns its colour value.



POKE  DPOKE  LPOKE
Syntax:    POKE x,n
           DPOKE x,n
           LPOKE x,n
Action:    Writes 1, 2 or 4 bytes into memory at an address which
           starts at 'x'.
           The value of 'x' must be an even number for DPOKE and
           LPOKE.



POLYLINE   POLYFILL  POLYMARK
Syntax:    POLYLINE n,x(),y()[OFFSETx_off,y_off]
           POLYFILL n,x(),y()[OFFSETx_off,y_off]
           POLYMARK n,x(),y()[OFFSETx_off,y_off]
Action:    POLYLINE  draws  a polygon with  n  corners.  The  x,y
           coordinates for the corner pointa are given in  arrays
           x()   and  y().   The  first  and  last   points   are
           automatically connected. The optional parameter OFFSET
           can be added to these coordinates.
           POLYFILL fills the polygon with the pattern previously
           defined by DEFFILL.
           POLYMARK  marks  the  corner  points  with  the  shape
           defined by DEFMARK.



POS
Syntax:    POS(n)
Action:    Returns the column in which the cursor is positioned.
           'n', a hypothetical argument, is optional.
           See also CRSCOL, CRSLIN, TAB, HTAB, VTAB.



PRBOX
Syntax:    PRBOX x,y,x1,y1
Action:    Draws a filled rectangle with rounded corners.
           See also BOX, PBOX, RBOX.


PRED
Syntax:    a$=PRED(b$)
Action:    Supplies  the character with the ASCII code  one  less
           than  that  of the first character  of  the  specified
           string.
           See also SUCC.


PRED()
Syntax:    i%=PRED(n%)
Action:    Returns the next lower number of the integer argument.
           See also SUCC().



PRINT
Syntax:    PRINT
           PRINT expression
Action:    Displays information on the screen.
           'expr' can be any number of expressions which must be
           separated by commas, semicolons or apostrophes.
           ; -items are printed one after an other in one line.
           , -items are printed at intervals of 16 columns.
           ' -each apostrophe causes a space to be printed.




PRINT AT
Syntax:    PRINT AT(column,row);expression
Action:    Prints  'expression'  at a specified row  and  column.
           NB. These start at 1, not 0.




PRINT USING
Syntax:    PRINT USING format$,expression[;]
           PRINT AT(column,row);USING format$,expression[;]
Action:    Prints formatted digits and character strings.
           format$ is a string expression which sets the printing
           format using a list of expressions separated by commas.

           #    reserves space for a digit.
           .    position of the decimal point.
           +    executes a plus sign.
           -    reserves space for a minus sign.
           *    zeros before the comma are replaced by * otherwise
                the same as #.
           $    prefix $.
           ,    insertion of a comma.
           ^    execution in exponent form  E+
           !    indicates that the first character of a string is
                issued.
           &    the whole string is issued.
        \..\    as many characters as the length of \..\ is issued
                (including back-slashes).
           -    prints the proceeding character.



PRINT TAB
Syntax:    PRINT TAB(n)
Action:    Prints  spaces  until  POS(0)  reaches  n.  If  POS(0)
           already exceeds n then a Line Feed/Carriage Return  is
           executed first.



PRINT#
Syntax:    PRINT #n,expression
           PRINT #n,USING format$,expression
Action:    Outputs data to a specified channel n  (0-99).  PRINT#
           USING allows formatted data to be output.


PROCEDURE
Syntax:    PROCEDURE proc[(var1,var2,...)]
Action:    Marks the beginning of a procedure.
           Basic will only process a procedure when it is called
           by the command GOSUB   (or   by  simply   naming   the
           procedure, or using  @proc. If it comes across the command
           procedure during 'normal' running of the program, it
           considers it to be the end of the program.
           Not  only  the  values  of  variable,   but  also  the
           variable's  address can be passed to procedures  using
           the VAR command in the Procedure's header.



PSAVE
Syntax:    PSAVE f$
Action:    Saves the current program to disk with the name f$, it
           is saved with protection,  and cannot be  subsequently
           listed    on   re-loading;    PSAVEd   programs    RUN
           automatically on loading.
           See also SAVE



PTSIN      Address of the VDI point input table
PTSOUT     Address of the VDI point output table
           These two commands can be used with index,  to address
           the array directly. eg. PTSIN(0).



PTST()
Syntax:    a=PTST(x,y)
Action:    Corresponds to the POINT command.  Returns the  colour
           of the pixel at x,y.


PUT
Syntax:    PUT x,y,section$[,mode]
Action:    Places a graphics block on the screen at x,y which
           has been previously grabbed by GET, and stored in
           section$.
           'mode' (optional) sets the way the image is placed.
           0 -                All points are cleared
           1 - s AND d        Only points set in both remain set.
           2 - s AND (NOT d)  Sets  only points which are  set  in
                              the   source   and  clear   in   the
                              destination.
           3 - s              Overwrite (default GRAPHMODE 1)
           4 - (NOT s)AND d
           5 - d
           6 - s XOR d
           7 - s OR d
           8 - NOT(s OR d)
           9 - NOT(s XOR d)
           10  NOT d
           11  s OR(NOT d)
           12  NOT s
           13  (NOT s)OR d
           14  NOT(s AND d)
           15  1              All points set.
           The important ones are:
           3   Repalce
           4   XOR
           7   Transparent
           13  Inverse Transparent.



PUT #
Syntax:    PUT #n[,r]
Action:    Writes a record to a random access file.
           'n' data channel number (0 to 99).
           'r' is an integer expression between 1 and the number
           of records in the file (max 65535) and denotes the
           record number of the record to be written.
           See also GET #, RECORD #




QSORT
Syntax:    QSORT a(s) [OFFSET o] [WITH i()] [,n[,j%()]]
           QSORT x$(s) WITH i() [,n[,j%()]]
Action:    Sorts  the elements of an array.  's' can be  a  minus
           sign or a plus sign,  indicating an ascending  sort(+)
           or a descending sort(-),  the default being ascending.
           The  parameter 'n' specifies that only the  first  'n'
           elements  are to be sorted.  (Depends on OPTION  BASE)
           whether 0 or 1. If n=-1, then all elements are sorted.
           When  a further array is specified,  then  that  array
           will be sorted along with the first array.
           OFFSET   determines  how  many  characters   off   the
           beginning shall not be considered.
           During sorting of string arrays a sorting criteria can
           be  specified in an array of at least 256 elements  by
           using WITH.  Without using this option, a normal ASCII
           sort is used.
           eg:
           DIM a$(256)
           FILES "*.*" TO "liste"
           OPEN "i",#1,"liste"
           RECALL #1,a$(),-1,x%
           CLOSE #1
           QSORT a$() OFFSET 13,x%
           OPEN "o",#1,"con:"
           STORE #1,a$(),x%
           CLOSE
           Saves the directory as 'LISTE', then reloads the file,
           sorts the array, not on name but on file length.
           DIM x%(20)
           PRINT "Unsorted:        ";
           FOR i%=0 TO 10
             x%(i%)=RAND(9)+1
             PRINT x%(i%);"  ";
           NEXT i%
           PRINT
           '
           QSORT x%(),11
           PRINT "Ascending sort:  ";
           FOR i%=0 TO 10
             PRINT x%(i%);"  ";
           NEXT i%
           PRINT
           '
           QSORT x%(-),11
           PRINT "Descending sort: ";
           FOR i%=0 TO 10
             PRINT x%(i%);"  ";
           NEXT i%
           PRINT



QUIT
Syntax:    QUIT[n]
Action:    Terminate the program and leave GFA Basic.
           Returns  a  two byte integer to  the  calling  routine
           (normally the desktop).



RAD
Syntax:    RAD(degrees)
Action:    Converts  from  degrees  to  radians.  (equivalent  to
           x*PI/180).
           See also DEG



RAND
Syntax:    RAND(y)
Action:    Produces a 16 bit random integer in the range 0 to  y-
           1. Where y is an integer max value &HFFFF.


RANDOM
Syntax:    RANDOM(x)
Action:    Returns a random integer between 0 (inclusive) and
           'x' (exclusive).



RANDOMIZE
Syntax:    RANDOMIZE [y]
Action:    Initialises  the  random number  generator  [with  the
           value y].



RBOX
Syntax:    RBOX x,y,x1,y1
Action:    Draws a rectangle with rounded corners from the two
           diagonally opposite corner points 'x,y' and 'x1,y1'
           See also BOX, PBOX, PRBOX.



RCALL
Syntax:    RCALL addr,reg%()
Action:    Calls  an assembler routine (similar to  C:  or  CALL)
           with pre-allocated values in the registers.
           The integer array reg% must have 16 elements and holds
           the values.  At the end of the routine, the values are
           also returned in the array.
           Data registers d0 to d7    --->reg%(0) to reg%(7)
           Address registers a0 to a6 --->reg%(8) to reg%(14)
           User Stack Pointer (a7)    --->reg%(15)




RC_COPY
Syntax:    RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
Action:    Copies  rectangular screen sections between  areas  of
           memory.
           s_adr    source address
           sx,sy    top left corner of source rectangle
           sw,sh    width & height  "   "        "
           d_adr    destination address
           dx,dy    destination x and y coordinates
           m        optional mode (see PUT for modes).



RC_INTERSECT
Syntax:    y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
Action:    Detects whether two rectangles overlap. The rectangles
           being  specified  by the coordinates of the  top  left
           corner(x,y)  and their width & height  (w,h).
           Returns TRUE (-1) if they do overlap and the variables
           x2,y2,w2,h2 contain the size of the common rectangle.



READ
Syntax:    READ var[,var1, ...]
Action:    Reads values from a DATA command and assigns them to a
           variable 'var'. Reading is taken from the last point a
           RESTORE was done (if any).



RECALL
Syntax:    RECALL #i,x$(),n[TO m],x
Action:    Inputs n lines from a text file to the array x$().  If
           n=-1  all  available lines are read.  x  contains  the
           number of lines read.


RECORD



RELSEEK
Syntax:       RELSEEK [#]N,X
Action:   Moves tINT
           '
           QSORT x%(-),11
           PRINT "Descending sort: ";
           FOR i%=0 TO 10
             PRINT x%(i%);"  ";
           NEXT i%
           PRINT



QUIT
Syntax:    QUIT[n]
Action:    Terminate the program and leave GFA Basic.
           Returns  a  two byte integer to  the  calling  routine
           (normally the desktop).



RAD
Syntax:    RAD(degrees)
Action:    Converts  from  degrees  to  radians.  (equivalent  to
           x*PI/180).
           See also DEG



RAND
Syntax:    RAND(y)
Action:    Produces a 16 bit random integer in the range 0 to  y-
           1. Where y is an integer max value &HFFFF.


RANDOM
Syntax:    RANDOM(x)
Action:    Returns a random integer between 0 (inclusive) and
           'x' (exclusive).



RANDOMIZE
Syntax:    RANDOMIZE [y]
Action:    Initialises  the  random number  generator  [with  the
           value y].



RBOX
Syntax:    RBOX x,y,x1,y1
Action:    Draws a rectangle with rounded corners from the two
           diagonally opposite corner points 'x,y' and 'x1,y1'
           See also BOX, PBOX, PRBOX.



RCALL
Syntax:    RCALL addr,reg%()
Action:    Calls  an assembler routine (similar to  C:  or  CALL)
           with pre-allocated values in the registers.
           The integer array reg% must have 16 elements and holds
           the values.  At the end of the routine, the values are
           also returned in the array.
           Data registers d0 to d7    --->reg%(0) to reg%(7)
           Address registers a0 to a6 --->reg%(8) to reg%(14)
           User Stack Pointer (a7)    --->reg%(15)




RC_COPY
Syntax:    RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
Action:    Copies  rectangular screen sections between  areas  of
           memory.
           s_adr    source address
           sx,sy    top left corner of source rectangle
           sw,sh    width & height  "   "        "
           d_adr    destination address
           dx,dy    destination x and y coordinates
           m        optional mode (see PUT for modes).



RC_INTERSECT
Syntax:    y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
Action:    Detects whether two rectangles overlap. The rectangles
           being  specified  by the coordinates of the  top  left
           corner(x,y)  and their width & height  (w,h).
           Returns TRUE (-1) if they do overlap and the variables
           x2,y2,w2,h2 contain the size of the common rectangle.



READ
Syntax:    READ var[,var1, ...]
Action:    Reads values from a DATA command and assigns them to a
           variable 'var'. Reading is taken from the last point a
           RESTORE was done (if any).



RECALL
Syntax:    RECALL #i,x$(),n[TO m],x
Action:    Inputs n lines from a text file to the array x$().  If
           n=-1  all  available lines are read.  x  contains  the
           number of lines read.
           The  optional parameter TO will read in the  start  of
           the file to the named elements of the array.
           eg.
           DIM a$(20)
           FOR n=0 TO 19
             a$(n)="Line # "+STR$(n)
           NEXT n
           OPEN "o",#1,"test"
           STORE #1,a$()
           CLOSE
           DIM b$(20)
           OPEN "i",#1,"test"
           RECALL #1,b$(),12 TO 15,x
           'or RECALL #1,b$(),-1,x
           CLOSE
           PRINT x
           FOR n=0 TO 20
             PRINT b$(n)
           NEXT n

See Also:  STORE



RECORD
Syntax:    RECORD #n,r
Action:    Sets  the  number of the next record to br read  or  stored
           with GET or PUT.

Example:   RECORD #1,15

See Also:  FIELD,GET#, PUT#, SEEK



RELSEEK
Syntax:    RELSEEK [#]n,x
Action:    Moves the random access file pointer forward (+X) or
           backwards (-X) 'X' number of bytes.


REM
Syntax:    REM remark
Action:    Whatever follows a REM coomand on a particular line
           is ignored by Basic. ' is synonoymous with REM.

Example:   REM This is a comment



RENAME
Syntax:    RENAME old$ AS new$
Action:    Renames a file.



REPEAT...UNTIL
Syntax:    REPEAT
           UNTIL end
Action:    Creates a pre-defined loop. The section of the program
           between repeat and until is repeated continuously until
           the condition is fulfilled.

Example:   REPEAT
           UNTIL MOUSEK       'Waits for mouse key to be pressed.



RESERVE
Syntax:    RESERVE n
Action:    Increases or decreases the memory used by basic
           'n' is a numeric expression which determines how big
           FRE(0) should be after this command. (see HIMEM, EXEC)

Example:   RESERVE 2560
           EXEC 0,"\PROGRAM.PRG","",""
           RESERVE

           2560  bytes  are  reserved and PROGRAM.PRG  is  loaded  and
           started. After running the reserved space is restored.

           Memory can be reserved in blocks of 256 bytes.
           If  n  is  negative then the whole of the  free  memory  is
           reserved.


RESTORE
Syntax:    RESTORE [label]
Action:    Positions the data pointer for READ.
           Places the data pointer at the beginning, or behind the
           label names 'label'
           'label' can be any list of characters and can contain
           digits, letters, underscore and full stops.  Unlike
           other variable names it can begin with a digit.


RESUME
Syntax:    RESUME    RESUME NEXT    RESUME label
Action:    The  RESUME command is only meaningful with  error  capture
           (ON ERROR GOSUB) where it allows a reaction to an error.

           RESUME repeats the erroneous command.
           RESUME NEXT resumes program execution after an incorrect
           command.
           RESUME 'label' branches to the 'label'.
           If a fatal error occurs only RESUME 'label' is possible

Example:   ON ERROR GOSUB error_trap
           ERROR 5
           PRINT "and again..."
           ERROR 5
           PRINT "is not reached."
           '
           PROCEDURE error_trap
               PRINT "OK, error intercepted"
               RESUME NEXT
           RETURN



RETURN
Syntax:    RETURN
Action:    Terminates a sub-routine


Syntax:    RETURN x
Action:    If  the command RETURN is reached during program  ececution
           and  is  within a FUNCTION...ENDFUNC  execution,  then  the
           value given after it is returned.


RIGHT$
Syntax:    RIGHT$(string[,n])
Action:    Returns the last characters or 'n' number of characters
           (from the right) of a character string 'string'
Example:   PRINT RIGHT$"Hello GFA",3)   'PRINTS GFA



RINSTR
Syntax:    RINSTR(a$,b$)
           RINSTR(a$,b$,[x])
           RINSTR([x],a$,b$)
Action:    Operates in same way as INSTR except that search begins  at
           the right end of a$.



RMDIR
Syntax:    RMDIR "directory name"
Action:    Deletes empty directories



RND
Syntax:    RND [(x)]
Action:    Returns a random number between 0 and 1

           The optional parameter (x) is disregarded, and  returns
           a random number between 0 (inclusive) and 1 (exclusive)

ROL
Syntax:    ROL(x,y)
           ROL&(x,y)
           ROL|(x,y)
Action:    Rotates a bit pattern left.


ROR
Syntax:    ROR(x,y)
           ROR&(x,y)
           ROR|(x,y)
Action:    Rotates a bit pattern right.


ROUND
Syntax:    ROUND(x[,n])
Action:    Rounds off the numeric expression x.

Example:   y=ROUND(-1.2)
           PRINT y,ROUND(1.7)


RSET
Syntax:    RSET a$=b$
Action:    Moves a string expression, right justified to a string.
See Also:  LSET,MID$


The  following  commands  are part  of  the  Resource  Library.  These
routines provide the creation of a graphical user interface.  The full
descriptions  of  these  functions  are  beyond  the  scope  of  these
abreviated  manual.  A full description is contained within  the  full
GFA-BASIC Reference manual and also the GFA-BASIC Software Development
Book.


RSRC_FREE
Syntax:    ~RSRC_FREE(0)
Action:    This  function  releases  the  memory  space  reserved   by
           RSRC_LOAD.
           Returns 0 if an error.


RSRC_GADDR
Syntax:    ~RSRC_GADDR(type,index,addr)
Action:    This   function  determines  the  address  of  a   resource
           structure   after  it  has  been  loaded  with   RSRC_LOAD.
           Depending  on the version of GEM,  this function  may  only
           work for Object trees and Alert boxes.
           Returns 0 if an error.

           Type:0   OBJECT TREE
                1   OBJECT
                2   TEDINFO
                3   ICONBLK
                4   BITBLK
                5   STRING
                6   image data
                7   obspec
                8   te_ptext
                9   te_ptmplt
               10   te_pvalid
               11   ib_pmask
               12   ib_pdata
               13   pb_ptext
               14   bi_pdata
               15   ad_frstr
               16   ad_frimg

           Index:   The   number  of  the  object  whose  address   is
                    required, counting objects of that type one by one
                    from the beginning of the resource file.

           addr:    The required address.

Example:   ~RSRC_GADDR(0,0,TREE%)



RSRC_LOAD
Syntax:    RSRC_LOAD(name$)
Action:    This  function reserves memory and loads a  resource  file.
           Then  internal  pointers are set and  the  co-ordinates  of
           characters converted into pixel format.

Example:   ~RSRC_LOAD("TEST.RSC")



RSRC_OBFIX
Syntax:    RSRC_OBFIX(tree,obj)
Action:    This function converts the coordinates of an object  within
           a  tree,  from character coordinates to pixel  coordinates,
           taking  into account the current screen resolution.  It  is
           automatically called by RSRC_LOAD,  but must be used if the
           object is created direct in memory by POKE.

           tree:    address of the object tree
           obj:     object number



RSRC_SADDR
Syntax:    RSRC_SADDR(type,index,addr)
Action:    This function sets the address of an object.
           Returns 0 if an error.

           type:    type of structure
           index:   the number of the object
           addr     address



RUN
Syntax:    RUN(a$)
Action:    Runs the program in memory,  or if a file name is  supplied
           will load and then run the appropriate program.

Example:   RUN "A:\PROGRAM.GFA"



SAVE
PSAVE
Syntax:    SAVE a$
           PSAVE a$
Action:    Saves a program file (psave is with list protection)
           'file name' is the name of the program.
           Programs which are saved with psave are not listed but
           run straight after the command 'load' is given.


SEEK
Syntax:    SEEK [#]n,x
Action:    Sets the file pointer on the byte number 'x' of file #n
           'n' is an integer expression between 0 and 99 which
           refers to the channel number.  'x' has a value (total)
           either greater or smaller than the length of the file
           addressed.



SCRP_READ
Syntax:    SCRP_READ(path$)
Action:    This  function reads data,  left there by another  program,
           from a small internal buffer,  thus allowing  communication
           between GEM programs. Returns 0 if an error.
Example:   SCRP_READ(a$)
See Also:  SCRP_WRITE



SCRP_WRITE
Syntax:    SCRP_WRITE(path$)
Action:    This  function writes data,  into a small internal  buffer,
           thus allowing communication between GEM programs.
Example:   SCRP_WRITE("A:\PROGRAM.TXT")
See Also:  SCRP_READ



SDPOKE
Syntax:    SDPOKE x,y
Action:    Allows  DPOKE  to  operate  in  supervisor  mode,  so  that
           protected address (0 to 2047) can be modified.



SEEK
Syntax:    SEEK #n,pos
Action:    Absolute  positioning  of data pointer  within  file.  This
           allows  the realisation of indexed sequential file  access.
           The  numerical expression n contains the channel number  of
           the file.


SELECT
Syntax:    SELECT x
           CASE y [TO z] or CASE y [,z,...]
           CASE TO y
           CASE y TO
           DEFAULT
           ENDSELECT
           CONT
Action:    A conditional command which enables execution of  specified
           program segments depending on an integer.

           The maximum of a CASE is 4 characters (eg CASE "A,B,C,D"

           The  CONT command provides a method of jumping over a  CASE
           or DEFAULT command.

Example:   REPEAT
               a%=ASC(INKEY$)
               SELECT a%
               CASE 65 TO 90
                    PRINT "CAPITAL LETTER"
               CASE 97 TO 122
                    PRINT "LOWER CASE LETTER"
               DEFAULT
                    PRINT "NOT CAPITAL OR LOWER CASE"
               ENDSELECT
           UNTIL a%=27


SETCOLOR
Syntax:    SETCOLOR i,r,g,b
           SETCOLOR i,n
Action:    Defines the colours red, green and blue for the colour
           register 'i'.
           'r,g,b' are the levels of the three primary colours
           from 0 to 7.
           Another way of defining colours is to use the value 'n'
           where n=r*256+g*16+b
See Also:  COLOR,VSETCOLOR



SETDRAW    See DRAW command.

SETMOUSE
Syntax:    SETMOUSE mx,my,[,mk]
Action:    The  SETMOUSE command permits the positioning of the  mouse
           cursor under program control. Tje optional parameter mk can
           simulate the mouse button being pressed or released.

Example:   FOR i%=0 TO 300
               HIDEM
               SETMOUSE i%,i%
               PLOT MOUSEX,MOUSEY
               SHOWM
               PAUSE 2
           NEXT i%


SETTIME
Syntax:    SETTIME time$,date$
Action:    Sets the time and the date.

           time$ is a string expression which contains the
           time.  hours, minutes and second can be displayed. The
           colons are optional as two digits have to be entered.
           The seconds can also be left out.

           date$ is a character string expression for the
           date.  It must always contain:  day, month and year,
           each separated by a full stop.

Example:   PRINT DATE$,TIME$
           SETTIME "17:30:30","27.10.1952"
           PRINT DATE$,TIME$



SGET
Syntax:    SGET screen$
Action:    Fast reading of the entire screen area into a string
           variable.
Example:   PCIRCLE 100,100,50
           SGET b$
           ~INP(2)
           CLS
           ~INP(2)
           SPUT b$
See Also:  SPUT, GET, PUT and BMOVE



SGN
Syntax:    SGN(x)
Action:    Ascertains whether 'x' is positive, negative or 0
           'x' can be any numeric expression.  SGN(x) is the
           mathematic sign function.


The  following  commands  are part of the  Shell  Library  and  enable
an  application  to  call  another,   preserving  both  the   original
application and its environment.
The full descriptions of these functions are beyond the scope of these
abreviated  manual.  A full description is contained within  the  full
GFA-BASIC Reference manual.



SHEL_ENVRN
Syntax:    SHEL_ENVRN(addr,search$)
Action:    This function determines the values of variables in the GEM
           environment.
           Returns 1.

           search$: The string to be sought
           addr:    address of the byte following the string

Example:   PRINT SHEL_ENVRN(a%,"PATH")
           PRINT CHAR{a%-4}

           ' Displays: PATH=A:\


SHEL_FIND
Syntax:    SHEL_FIND(paths$)
Action:    This  function  searches for a file and supplies  the  full
           file specification.  First the path on the current drive is
           searched, then the root directory of drive A:.

           Returns 0 if file not found, or 1 if found.

           On entry:
           path$:   String contains sought after filename.

           On exit:
           path$:   Contains  the full file specification if the  file
                    was found, otherwise it is unchanged.





SHEL_GET
Syntax:    SHEL_GET(num,x$)
Action:    This  function  reads data from  the  GEMDOS  environmental
           string  buffer (into which the file DESKTOP.INF is read  on
           start up).

           Returns 0 if an error.

           num:     number of bytes to be read
           x$:      string to contain data

Example:   SHEL_GET(500,x$)
           PRINT x$



SHEL_PUT
Syntax:    SHEL_PUT(len,x$)
Action:    This  function  writes data into the  GEMDOS  environmental
           string buffer.

           Returns 0 if an error.

           x$:      String containing the data to be written
           len:     number of bytes to be written

Example:   'Register GFA-BASIC
           ~SHEL_GET(2000,a$)
           q%=INSTR(a$,CHR$(26))
           IF q%
               a$=LEFT$(a$,q%-1)
               IF INSTR(a$,"GFABASIC.PRG")=0
                    a$=s$+"#G 03 04 A:\GFABASIC.PRG@*.GFA
                              +MKI$(&HDOA)+CHR$(26)
                    ~SHEL_PUT(LEN(a$),a$)
               ENDIF
           ENDIF

           '  Registers that all .GFA files cause GFABASIC.PRG  to  be
           loaded when clicked on.



SHEL_READ
Syntax:    SHEL_READ(cmd_string$,tail_string$)
Action:    This function allows the program to identify the command by
           which   it   was  invoked  and  supplies   the   name,   eg
           GFABASIC.PRG, and the command line if any.

           cmd_string$        string  variable to contain the  command
                              line.

           tail_string$       string variable to contain name.




SHEL_WRITE
Syntax:    SHEL_WRITE(prg,grf.gem.cmd$,nam$)
Action:    This  function informs the AES that another application  is
           to  be  started after the current one  has  terminated.  In
           contrast to p_exec (GEMDOS 75), however the current program
           does not remain in memory.

           prg:     0 Back to desktop
                    1 Load new program
           grf:     0 TOS program
                    1 Graphic application
           gem:     0 not a GEM application
                    1 GEM application
           cmd$     command line string
           nam$     name of next application

Example:   ~SHEL_WRITE(1,1,1,"","GFABASIC.PRG")


SHL
Syntax:    SHL(x,y)
           SHL&(x,y)
           SHL|(x,y)
Action:    Shifts a bit pattern left



SHOWM
Syntax:    SHOWM
Action:    Makes the mouse pointer appear.
See Also:  HIDEM



SHR
Syntax:    SHR(x,y)
           SHR&(x,y)
           SHR|(x,y)
Action:    Shifts a bit pattern right


SIN
Syntax:    SIN(x)
Action:    Returns the sine value of 'x'



SINGLE{}
Syntax:    SINGLE{x}
Action:    Reads/writes  a  4  byte floating point  variable  in  IEEE
           single precision format.


SINQ
Syntax:    SINQ(degrees)
Action:    Returns the extrapolated sine of a numeric expression.



SLPOKE
Syntax:    SLPOKE x,y
Action:    Allows  LPOKE  to  operate  in  supervisor  mode,  so  that
           protected address (0 to 2047) can be modified.


SOUND
Syntax:    SOUND chn,vol,note,octave[,dur]
           SOUND chn,vol,note,#period[,dur]
Action:    GENERATES MUSICAL NOTES
           'chn' is a 1, 2, or 3 and selects the sound channel.
           'vol' selects the volume.
           'note' is a value of 1 to 12 and selects notes:
               1=C,
               2=C#
               3=D
               4=D#
               5=E
               6=F
               7=F#
               8=G
               9=G#
               10=A
               11=A#
               12=B
           'octave' is between 1 and 8, and determines octave.
           'dur' is the time in 1/50ths of a second that GFA Basic
           has to wait before execution of the next command.
           A further possibility to choose the pitch is to enter
           'period'  prefixed by '#' instead of 'note' and 'octave'.
           The period can be calculated from the
           frequency with:

           Period = TRUNC(125000/frequency +0.5)



SPACE$
Syntax:    SPACE$(x)
Action:    Creates a character string containing 'x' spaces.



SPC
Syntax:    SPC(n)
Action:    Produces 'n' spaces in a print command



SPOKE    SDPOKE    SLPOKE
Syntax:    SPOKE x,n    SDPOKE x,    SLPOKE x,n
Action:    Writes 1, 2 or 4 bytes into an area of memory which
           begins with the address 'x'


SPRITE
Syntax:    SPRITE A$[,x,y]
Action:    Puts the sprite defined in a$ at (X,Y) or, if no
           coordinates are given, deletes it.
             A$ = MKI$(X POSITION)
              + MKI$(Y POSITION)
              + MKI$(0=NORMAL OR 1=XOR MODE)
              + MKI$(SCREEN COLOUR MOSTLY 0)
              + MKI$(SPRITE COLOUR MOSTLY 1)
              + BIT PATTERN OF SCREEN AND SPRITE

           Unlike defmouse, the bit patterns for screen and sprite
           are not stored in separate blocks but in alternate
           words (16 bits).
           If the same sprite is put onto the screen in another
           position then the first sprite is deleted.


SPUT
Syntax:    SPUT var
Action:    Fast copying of a 32000 byte string into the screen
           area.
See Also:  SGET, PUT, GET and BMOVE



SQR
Syntax:    SQR(X)
Action:    Calculates the square root of 'X'.



SSORT
Syntax:    SSORT a(s) {OFFSET o][WITH i()][,n[,j%()]]
           SSORT x$(s) WITH i() [,n[,j%{}]]
Action:    Sorts the elements in an array by its size using the Shell-
           Metzner method.

           a()      array or string array
           i()      integer array
           j%       4byte integer array
           x$()     string array
           s        + or - or no sign



STE?
Syntax:    STE?
Action:    Returns -1 for STE otherwise 0



STICK
Syntax:    STICK m
           STICK(p)
Action:    The function STICK(p) returns the position of a joystick.
           STICK 0 causes port 0 to supply mouse information.
           STICK 1 causes port 1 to read the joystick.

Example:   STICK 1
           REPEAT
               direction%=STICK(0)
               fire%=STRIG(0)
               SELECT direction%
               CASE 4
                    PRINT "LEFT"
               CASE 8
                    PRINT "RIGHT"
               CASE 2
                    PRINT "DOWN"
               CASE 1
                    PRINT "UP"
               ENDSELECT
           UNTIL fire!
           WHILE STRIG(0)
           WEND



STOP
Syntax:    STOP
Action:    Stops execution of a program.
           Unlike the END command it does not close any files and
           by typing CONT the program will resume from the line
           following the STOP command.



STORE
Syntax:    STORE #i,x$()[,n[TO m]]
Action:    Fast save of a string array as a text file. The instruction
           STORE  is  used for sending the contents of an array  to  a
           file or data channel (elements seperated by CR/LF).

See Also:  RECALL



STR $
Syntax:    STR$(X)
Action:    Transforms the value 'X' into a character string.



STRING$
Syntax:    STRING$(N,string)  OR  STRING$(N,C)
Action:    Produces a string formed by repeating 'string' or
           CHR$(C) 'N' times. 'N' is a number from 0 to 32767.



SUB
Syntax:    SUB VAR,N
Action:    Deducts 'N' from 'VAR'. Same as VAR=VAR-N but executes
           almost twice as fast.
Example:   x=57
           SUB x,3*5
           PRINT x  'PRINTS 42


SUB()
Syntax:    SUB(x,y)
Action:    Corresponds to x-y

Example:   PRINT SUB(5^3,4*20+3)   'PRINTS 42



SUCC()
Syntax:    SUCC(n)
Action:    Determines the next higher number.
See Also:  PRED()



SWAP
Syntax:    SWAP var1,var2
Action:    Exchanges the values of 'var1' and 'var2'.
           The variables must be of the same type.
           When swapping array fields the dimensions are also swap
           ped.


SWAP()
Syntax:    SWAP(n)
Action:    Swaps the high and low words of a varaible.




SYSTEM
Syntax:    SYSTEM
Action:    Causes a return to the desktop, same as quit.




TAB
Syntax:    TAB(n)
Action:    Sets the tabulator to the nth column.
           Tab can only be used in conjunction with the print
           command.
           If the current position is already past 'N' then the
           tab function is set for the next line.


TAN
Syntax:    TAN(X)
Action:    Returns the tangent of 'X' (X is the angle in radians).



TEXT
Syntax:    TEXT X,Y, [ L, ]string
Action:    Puts a text onto the screen at graphics coordinates
           'X,Y'. The graphics can first be defined by using
           the command DEFTEXT.



TIME$
Syntax:    TIME$
Action:    Returns the system time as a string.
           Format: hh:mm:ss and is updated every two seconds.

Example:   PRINT TIME$



TIME$=
Syntax:    TIME$=a$
Action:    The time can be set.

Example:   TIME$="20:15:30"



TIMER
Syntax:    t%=TIMER
Action:    TIMER suuplies the elapsed time in 1/200 seconds since  the
           system was started.

Example:   t%=TIMER
           FOR i%=1 TO 2500
           NEXT i%
           PRINT (TIMER-t%)/200;" Seconds"



TITLEW
Syntax:    TITLEW n,"title"
Action:    Gives the window number 'n', the new title 'title'.




TOPW
Syntax:    TOPW #1
Action:    Activates the windows number n.




TOUCH
Syntax:    TOUCH[#]n
Action:    Updates the date and time stamps od a file,  giving it  the
           current system time and date.

Example    OPEN "u",#1,"TEST.TXT"
           TOUCH #1
           CLOSE #1



TRACE$
Syntax:    TRACE$
Action:    The  variable TRACE$ contains the command which is next  to
           be processed.

See Also:  TRON,TROFF




TRIM$
Syntax:    TRIM$(a$)
Action:    Removes spaces at the beginning of a string expression.




TROFF
Syntax:    TROFF
Action:    Switches the trace function off.



TRON
Syntax:    TRON
Action:    Switches the trace function on. This causes each command to
           be listed on the screen.



TRON#
Syntax:    TRON #1
Action:    Switches the trace function on. This causes each command to
           be listed to the relevant channel number.



TRONproc
Syntax:    TRON tr_proc
Action:    A  procedure  can be specified which is called  before  the
           execution of each command.



TRUE
Syntax:    TRUE
Action:    Constant 0. This is simply another way of expressing
           the value of a condition when it is true and is equal
           to zero. (see also FALSE).



TRUNC
Syntax:    TRUNC(X)
Action:    Returns the integer portion of 'X'.




TT?
Syntax:    TT?
Action:    Returns -1 for 68020 or 68030 processeor, otherwise 0.



TYPE
Syntax:    TYPE(ptr)
Action:    Determines the type of the variable at which a pointer
           is set.

           'ptr' is an integer expression (usually *var).
           TYPE(ptr) returns a code according to the type of
           variable to which 'ptr' is pointing.

               0=var
               1=var$
               2=var%
               3=var!
               4=var()
               5=var$()
               6=var%()
               7=var!().

           On errors -1 is returned.



UPPER$
Syntax:    A$="basic"
           PRINT UPPER$(A$)
           PRINT UPPER$("1a")
Action:    Transforms all lower case letters of a string to upper
           case. Any non letter characters are left unchanged.



V:
Syntax:    V:x
Action:    Returns the address of a variable or strings or elements of
           an array.



VAL
Syntax:    VAL(X$)
Action:    Transforms 'X$' into a number, as far as possible.
           In the case of a purely alphabetical string the value
           0 is returned.


VAL?
Syntax:    VAL?(X$)
Action:    Determines the number of characters starting at the
           beginning of a string that can be converted into a
           numerical value with VAL.



VAR
Syntax:    name([a,b,...] VAR x,y..a(),b(),...)
Action:    Declaration  part of the parameter list for a PROCEDURE  or
           FUNCTION.

Example:   sum(13,12,a)
           sum(7,9,b)
           PRINT a,b
           '
           PROCEDURE sum(x,y,VAR z)
               z=x+y
           RETURN



VARIAT()
Syntax:    VARIAT(n,k)
Action:    Returns the number of permutations of n elements to the kth
           order without repitition.

Example:   PRINT VARIAT(6,2)       'prints 30

See Also:  FACT(), COMBIN()




VARPTR
Syntax:    VAPTR(var)
Action:    Determines the address or starting address of a
           variable 'var'.



VDIBASE
Syntax:    VDIBASE
Action:    Dangerous pokes!
           Determines the address above the area used by basic
           and the required tables and variables.
           This is the point from which this version of gem keeps
           parameters for the vdi (text style, clipping etc.).
           By use of peek and poke in this area, various effects
           (and nasty crashes!) can be obtained.



VDISYS
Syntax:    VDISYS[opcode [,c_int,c_pts[,subopc]]]
Action:    The  VDI function with function code opcode is  called.  If
           opcode is not specified,  then the function code must, like
           other  parameters,  be  placed in the  control  block  with
           DPOKE.

           The  depth  of  this command is betond the  scope  of  this
           abbreviated manual.



VOID
Syntax:    VOID exp
Action:    This command performs a calculation and forgets the
           result. Sounds silly but there are occasions when this
           command is required, eg. forced garbage collection
           (fre(0)), waiting for a keystroke (inp(2)), or calling
           various bios, xbios, gemdos or c: routines which have
           no parameters.



VQT_EXTENT
Syntax:    VQT_EXTENT(text$[,x1,y1,x2,y2,x3,y3,x4,y4])
Action:    Returns  the corner coordinates of a rectangle  which  will
           surround the text in text$.  The coordinates can either  be
           found in the variables x1,y1 to x4,y4, or in PTSOUT(7). The
           corner pointers are numbered in a clockwise direction.

Example:   INPUT text$
           CLS
           ATEXT 100,25,2,text$
           ~VQT_EXTENT(text$,x1,y1,x2,y2,x3,y3,x4,y4)
           BOX x4+100,y4+25,x2+00,y2+25



VQT_NAME
Syntax:    VQT_NAME(i,font_name$)
Action:    Supplies  the handle of the font with  the  indentification
           number  i and places the name of the loaded  character  set
           into the string variable font_name$.




VSETCOLOR
Syntax:    VSETCOLOR colour,red,green,blue
           VSETCOLOR colour,composite
Action:    Due to an error in TOS, SETCOLOR does not correspond to the
           registers used by COLOR. VSETCOLOR is used to overcome this
           problem.

           Low Resolution
           SETCOLOR     0 1 2 3 4 5 6 7 8  9 10 11 12 13 14 15
           VSETCOLOR    0 2 3 6 4 7 5 8 9 10 11 14 12 15 13  1

           Medium Resolution
           SETCOLOR     0 1 2 3
           VSETCOLOR    0 2 3 1

           High Resolution
           SETCOLOR 0,even = VSETCOLOR 0,0
           SETCOLOR 0,odd  = VSETCOLOR 0.&H777

           The  term  composite  is calculated the same  way  as  with
           SETCOLOR: ie rgb=(r*256)+(g*16)+b



VST_LOAD_FONTS
Syntax:    VST_LOAD_FONTS(x)
Action:    Loads   the   additional  character   sets   specified   in
           ASSIGN.SYS, and the number of loaded fonts is returned.

Example:   RESERVE 25600
           num_fonts%=VST_LOAD_FONTS(0)
           face%=VQT_NAME(num_fonts%,fonts$)
           FOR i%=1 to num_fonts%
               DEFTEXT,,,,face%
               TEXT 80,80,"This is the "+font$+" font."
               ~INP(2)
           NEXT i%
           ~VST_UNLOAD_FONTS(0)
           RESERVE


VST_UNLOAD_FONTS
Syntax:    VST_UNLOAD_FONTS(x)
Action:    Removes   the   character  set   previously   loaded   with
           VST_LOAD_FONTS from memory.



VSYNC
Syntax:    VSYNC
Action:    Enables synchronization with the screen by waiting
           until the next vertical sync pulse is received - helps
           avoid flickering of the screen during animation when  using
           GET and PUT.

Example:   t%=TIMER
           FOR i%=1 TO 100
               VSYNC
           NEXT i%
           PRINT SUB(TIMER,t%)/200
           ' PRINTS the time for 100 scans of screen.


VTAB
Syntax:    VTAB line
Action:    VTAB  positions the cursor to the specified column or  line
           number . Note that the cursor columns and lines are counted
           from 1, not 0.

See Also:  HTAB, PRINT AT, TAB


The  following  VDI  Workstation  routines  and  functions  are   only
available  if  GDOS  has been booted and a valid  ASSIGN.SYS  file  is
available.  In depth documentation on the VDI routines are beyond  the
scope of this abbreviated manual.  Further information can be found in
the full GFA-BASIC Interpreter Manual or Software Development Book.



V_CLRWK
Syntax:    V_CLRWRK()
Action:    This  function clears the output buffer.  For  example  the
           screen or the printer buffer is cleared.



V_CLSVWK
Syntax:    V_CLSVWK(id)
Action:    Closes a virtual workstation opened with V_OPNVWK.



V_CLSWK
Syntax:    V_CLSWK()
Action:    Closes the current workstation opened with V_OPNWK().



V_OPNVWK
Syntax:    V_OPNVWK(id,1,1,1,1,1,1,1,1,1,2)
Action:    Opens  a virtual screen driver and supplies the handle  for
           the specified device id.



V_OPNWK
Syntax:    V_OPNWK(id)
Action:    Supplies the handle for the specified device id.



V_UPDWK
Syntax:    V_UPDWK()
Action:    Sends buffered graphic instructions to the attached device.



V~H
Syntax:    V~H
Action:    Returns the internal VDI handle of GFA-BASIC.

           V~H=x    'Sets internal VDI handle

           V~H=-1   'Sets VDI handle to value from V_OPNVWK()


W:
Syntax:    W:x
Action:    Allows  passing of numerical expressions to  the  operating
           system and C routines as a word (2-byte).

See Also:  L:



WAVE
Syntax:    WAVE voice,env,form,per,del
Action:    Produces noises from the three sound channels.
           WAVE 0,0 switches off all sound channels.

           voice:   Any  channel  or combination of  channels  may  be
                    activated  simultaneously.  The value of voice  is
                    256 * by the period.

                    1 Channel 1
                    2 Channel 2
                    4 Channel 3
                    8 Noise (Channel 1)
                   16 Noise (Channel 2)
                   32 Noise (Channel 3)

           env:     Specifies  the channels for which the wnvelope  is
                    to be active.

                    1 Channel 1
                    2 Channel 2
                    3 Channel 3

           form:    Envelope shape

                    0 - 3     As 9
                    4 - 7     As 15
                    8         Falling sawtooth
                    9         Falling linear
                    10        Triangle falling
                    11        Falling linear, then to max
                    12        Rising sawtooth
                    13        Rising linear and holding
                    14        Triangle, then rising
                    15        Linear rising, then to zero

           per:     Period of the waveform multiplied by 125000.

           del:     Delay in 1/59ths second before the next  GFA-BASIC
                    command is executed.

Example:   SOUND 1,15,1,4,20
           SOUND 2,15,4,4,20
           SOUND 3,15,8,4,20
           WAVE 7,7,0,65535,300
           '  A tone is generated from each channel then modulated  by
           '  WAVE.

See Also:  SOUND




WHILE....WEND
Syntax:    WHILE condition
           WEND
Action:    Creates a conditional loop between while and wend until
           the 'condition' is fulfilled. This is checked at the
           beginning of the loop and so it is possible that the
           loop is never executed.


The following functions are all functions of the Window Library


WINDTAB
Syntax:    WINTAB
           WINTAB(i,j)
Action:    Gives the address of the Window Parameter Table. This table
           contains  the  data  that determines the  appearance  of  a
           window.

           Window Parameter Table:

           Offset
           0        Handle of Window 1
           2        Attributes for Window 1
           4        x coordinates of Window 1
           6        y coordinates of Window 1
           8        Width of Window 1
           10       Height of Window 1
           12-22    Parameters for Window 2
           24-34    Parameters for Window 3
           36-46    Parameters for Window 4
           48       -1
           50       0
           52-58    Coordinates and size of Desktop
           60-63    Coordinates of the joint of the four windows
           64-65    Origin for graphic instructions (CLIP OFFSET)

           Window Attibute element:

           Bit
           0        Window Title
           1        Close box
           2        Full box
           3        Move box
           4        Information line
           5        Sizing box
           6        Up arrow
           7        Down arrow
           8        Vertical slider
           9        Left arrow
           10       Right arrow
           11       Horizontal slider


Example:   OPEN #1,100,120,200,70,&HFFF
           ' corresponds to:
           DPOKE WINTAB+2,&HFFF
           DPOKE WINTAB+4,100
           DPOKE WINTAB+6,120
           DPOKE WINTAB+8,200
           DPOKE WINTAB+10,70
           OPENW 1
           ' or
           WINTAB(1,1)=&HFFF
           WINTAB(1,2)=100
           WINTAB(1,3)=120
           WINTAB(1,4)=200
           WINTAB(1,5)=70
           OPENw 1

WIND_CALC
Syntax:    WIND_CALC(w_type,attr,ix,iy,iw,ih,ox,oy,ow,oh)
Action:    This function computes the total size of the work area from
           the size of the window.
           Returns 0 if an error.

           w_type:            0 Compute total size
                              1 Compute work area size

           attr:              Bit
                              0   Title bar with name
                              1   Close box
                              2   Full size box
                              3   Move bar
                              4   Info line
                              5   Size box
                              6   Up arrow
                              7   Down arrow
                              8   Vertical slider
                              9   Left arrow
                              10  Right arrow
                              11  Horizontal slider

           ix,iy              top left coorinates
           iw,ih              width and height

           ox,oy              Calculated top left coordinates
           ow,oh              Calculated width and height



WIND_CLOSE
Syntax:    WIND_CLOSE(handle)
Action:    Closes the specified window.



WIND_CREATE
Syntax:    WIND_CREATE(attr,wx,wy.ww.wh)
Action:    Allocates  a  new window,  specifying  the  attributes  and
           maximum size. The handle of the window is returned.

           attr:              Bit
                              0   Title bar with name
                              1   Close box
                              2   Full size box
                              3   Move bar
                              4   Info line
                              5   Size box
                              6   Up arrow
                              7   Down arrow
                              8   Vertical slider
                              9   Left arrow
                              10  Right arrow
                              11  Horizontal slider

           wx                 Max x position of left edge
           wy                 Max y position of top edge
           ww                 Max width of window
           wh                 Max height of window


WIND_DELETE
Syntax:    WIND_DELETE(handle)
Action:    Deletes a window allocation and frees reserved memory.



WIND_FIND
Syntax:    WIND_FIND(fx,fy)
Action:    Determines  the  id  number of a window  within  which  the
           specified coordinates lie.

           fx:                x coordinates
           fy:                y coordinates



WIND_GET
Syntax:    WIND_GET(handle,code,w1,w2,w3,w4)
Action:    Supplies information about a window determined by the code.

           handle:            Id number of the window

           code:              depending upon the code,  information is
                              supplied in w1,w2,w3,w4.


           code: 4            supplies size of window work area
                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 5            supplies  total  size of  entire  window
                              including borders

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 6            supplies total size of previous window

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 7            supplies  the  total  max  size  of  the
                              window.

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 8            supplies the position of the  horizontal
                              slider

                    w1:       1=far left  1000=far right

           code: 9            supplies the position of the  vertical
                              slider

                    w1:       1=top  1000=bottom

           code: 10           supplies  the  id  number  of  the   top
                              (active) window

                    w1:       id number of active window

           code: 11           supplies  the coordinates of  the  first
                              rectangle  in the  specified  rectangle
                              list.

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 12           supplies  the  coordinates of  the  next
                              rectangle   in  the  specified   windows
                              rectangles list

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height


           code: 13           reserved

           code: 15           supplies  the  size  of  the  horizontal
                              slide bar compared to its max possible

                    w1:       -1 = minimum size
                               1 = small
                               1000 = full width

           code: 16           supplies the size of the vertical  slide
                              bar compared to its max possible

                    w1:       -1 = minimum size
                               1 = small
                               1000 = full height

WIND_OPEN
Syntax:    WIND_OPEN(handle,wx,wy,ww,wh)
Action:    Draws  on  the  screen a  window  previously  created  with
           WIND_CREATE.


WIND_SET
Syntax:    WIND_SET(handle,code,w1,w2,w3,w4)
Action:    Changes  the parts of a window according to  the  specified
           function code.

           code: 1            Sets  new  windows  components  as  with
                              WIND_CREATE.

                    w1:       new window element

           code: 2            Gives a window a new title

                    w1:       Hi word
                    w2:       Low word of address of title string

           code: 3            Specifies a new information line
                    w1:       Hi word
                    w2:       Low  word  of  address  of   information
                              string

           code: 5            Sets the window size

                    w1:       x coordinates
                    w2:       y coordinates
                    w3:       width
                    w4:       height

           code: 8            Positions the horizontal slider

                    w1:       1=far left  1000=far right

           code: 9            Positions the vertical slider

                    w1:       1=top  1000=bottom

           code: 10           Sets top (active) window

                    w1:       id number

           code: 14           Sets a new desk top Menu tree

                    w1:       Low word
                    w2:       High word of address of new tree
                    w3:       id  number  of the first  object  to  be
                              drawn

           code: 15           Sets the size of the vertical slide bar

                    w1        -1=minimum size
                              1= small
                              1000 max size

           code: 16           Sets  the size of the horizontal  slider
                              bar

                    w1        -1=minimum size
                              1= small
                              1000 max size

WIND_UPDATE
Syntax:    WIND_UPDATE(flag)
Action:    Coordinates  all functions concerned with  screen  redraws,
           in particular with drop down menus.

           flag: 0            screen redraw completed
                 1            screen redraw starting
                 2            application loses mouse control
                 3            application takes on mouse control


WORD()
Syntax:    WORD(x)
Action:    Extends  a  word to long word length (32 bits)  by  copying
           bits  15  to bit positions 16 to 31,  thus  preserving  the
           sign.


WORK_OUT()
Syntax:    WORK_OUT(x)
Action:    Determines  the  values found in INTOUT(0)  to  INTOUT(44),
           PTSOUT(0)  and PTSOUT(1) after returning from the  function
           OPEN_WORKSTATION.



WRITE
Syntax:    WRITE [ expressions ][ ; ]
           WRITE #n [ expressions ][ ; ]
Action:    Stores data in a sequential file to be read with input.
           Unlike the PRINT command the numbers are separated by
           commas and the strings are enclosed in quotes.



WRITE#
Syntax:    WRITE#n,expression
Action:    Saves  data  to sequential file,  for  later  reading  with
           INPUT#.

Example:   OPEN "o",#1,"TEST.DAT"
           WRITE #1,"Version ",3,".6"
           CLOSE #1
           OPEN "i",#1,"TEST.DAT"
           INPUT #1,v1$,v2$,v3$
           CLOSE #1
           PRINT v1$+V2$+v3$



W_HAND
Syntax:    W_HAND(#n)
Action:    Returns  the GEM handle of the window whose channel  number
           is n.

Example:   OPENW 2
           PRINT W_HAND(#2)
           ~INP(2)
           CLOSE #2


W_INDEX
Syntax:    W_INDEX(#hd)
Action:    Returns the window number of the specified GEM handle.
           Reverse of W_HAND().




XBIOS

The XBIOS function is used to call XBIOS system routines.

~XBIOS(0,t%,l:p%.l:v%)

           Initialises  the mouse handling routine but not  compatible
           with GEM.

           t%  0    Switches mouse off
               1    Switches mouse into relative mode
               2    Switches mouse into absolute mode
               4    Mouse in keyboard mode
           p%       Address of information structure
           v%       Address of the mouse handling routine

r%=XBIOS(2)

           Returns the base address of the physical screen memory.

           r%       Address of the physical screen memory

r%=XBIOS(3)

           Returns  the  address  of the logical  screen  memory  when
           writing to the screen.

           r%       Address of the logical screen memory

r%=XBIOS(4)

           Returns the current screen resolution

           r%  0    320 x 200
               1    640 x 200
               2    640 x 400

~XBIOS(5,l:l%,l:p%,r%)

           Enables the resolution to be changed from low res and  high
           res when using a colour monitor. Can not be used with GEM.

           l%       New address of logical screen memory
           p%       New address of the physical screen memory
           r%       New screen resolution (see XBIOS(4))

~XBIOS( 6,L:adr%)

           Allows all colour registers to be reset at one time.

           adr%     Address of a table of 16 words, which contains new
                    pallete data.

r%=XBIOS(7,n%,c%)

           Sets or gets a colour register.

           r%       For  c%=-1 the previous specified colour  register
                    is returned.
           n%       Colour register
           c%       New colour, at c%=-1 see r%

r%=XBIOS(8,L:b%,L:f%,d%,sec%,t%,side%,n%)

           Reads sectors of a disk

           r%       0 if no error
           b%       address of the area from which sectors are read
           f%       unused
           d%       drive number (0=A, 1=B etc)
           sec%     sector number
           t%       track number
           side%    disk side (0 or 1)
           n%       number of sectors to be read

r%=XBIOS(9,L:b%,L:f%,d%,sec%,t%,side%,n%)

           Writes sectors to a disk

           r%       0 if no error
           b%       address of the area to which sectors are written
           f%       unused
           d%       drive number (0=A, 1=B etc)
           sec%     sector number
           t%       track number
           side%    disk side (0 or 1)
           n%       number of sectors to be written

r%=XBIOS(10,L:b%,L:f%,d%,sec%,t%,side%,i%,L:m%,v%)

           A trace of the disk formats

           r%       0 if no error
           b%       address of an area for intermediate memory
           f%       unused
           d%       drive number (0=A, 1=B etc)
           sec%     sectors per track
           t%       track number to be formatted
           side%    disk side (0 or 1)
           i%       Interleave factor (normaaly 1)
           m%       Magic number &H87654321
           v%       value in sectors of format (normally &HE5E5

~XBIOS(12,n%,L:adr%)

           Outputs the contents of a block of memory to MIDI.

           n%       number of bytes -1
           adr%     address of the source storage area

~XBIOS(13,n%,L:adr%)

           Sets the MFP interrupt vector on the ST.  This can only  be
           used from assembly language or C and is not available  from
           GFA-BASIC.

           n%       Interrupt number
           adr%     new address of the interrupt

r%=XBIOS(14,d%)

           Returns  the  address of the I/O table used by  the  serial
           interface.

           r%       Address  of  the data buffer for  the  serial  I/O
                    table
           d%       0:        RS232
                    1:        IKBD
                    2:        MIDI

~XBIOS(15,b%,h%,ucr%,rsr%,tsr%,scr%)

           Configures  the  serial interface.  The  parameters  remain
           unchanged with a value of -1.

           b%       Baud rate
           h%       hand shake mode
                    0: no handshake
                    1: XON/XOFF
                    2: RTS/CTS
                    3: both
           ucr%     USART control register of MFP
           rsr%     receiver status register of MFP
           tsr%     transmitter status register of MFP
           scr%     synchronous character register of MFP

r%=XBIOS(16,L:us%,L:sh%,L:cl%)

           Changes the keyboard translation tables.

           r%       address of the KEYTAB structure
           us%      address of the table for keys without shift
           sh%      address of the table for keys with shift
           cl%      address of the table for keys with Cap-lock

r%=XBIOS(17)

           Returns a random number

           r%       number with 24 bit accuracy (0 to 16777215)

~XBIOS(18,L:b%,L:s%,d%,f%)

           Creates a boot sector for the disk in memory

           b%       address  of  a 512 byte buffer for  producing  the
                    boot sector
           s%       serial number that forms part of the boot sector
                    -1: previous serial retained
                    >24 bits: random number returned
           d%       disk type (tracks/sides)
                    0:40 tracks,single sided (180K)
                    1:40 tracks,double sided (360K, IBM)
                    2:80 tracks, single side (360K)
                    3:80 tracks, double sided (720K)
           f%       0:non executable boot sector
                    1:executable
                    -1:leave unchanged

r%=XBIOS(19,L:b%,L:f%,d%,sec%,t%,side%,n%)

           Verifies the disk contents

           b%       address of the memory area with which a comparison
                    is made.
           f%       not used
           d%       disk drive number
           sec%     start sector
           t%       track number
           side%    disk side
           n%       number of sectors

~XBIOS(20)

           Calls  the  hardcopy routine and thus dumps the  screen  to
           printer.

r%=XBIOS(21,c%,s%)

           Configure cursor.

           r%       when c%=5 returns the cursor blink rate
           c%       0: Hide cursor
                    1: Show cursor
                    2: blink cursor
                    3: solid cursor
                    4: blink rate set in s%
                    5: see r%
           s%       when c%=4, blink rate set to s%

~XBIOS(22,L:t%)

           Sets date and time

           t%       Bits 0-4:   seconds
                         5-19:  minutes
                         11-15: hours
                         16-20: day
                         21-24: month
                         25-31: year - 1980

r%=XBIOS(23)

           returns date and time

           r%       see XBIOS(22) for bit settings


~XBIOS(24)

           re   installs   the  original  keyboard   allocation   (see
           XBIOS(16))

XBIOS(25,n%,L:adr%)

           writes bytes from memory to the keyboard processor (IKBD)

           n%       number bytes-1 to be sent
           adr%     address where the data to be sent is stored

~XBIOS(26,i%)

           Disables an MFP interrupt.

           i%       interrupt number (0-15) to be disabled

~XBIOS(27,i%)

           enables an MFP interrupt.

           i%       interrupt number (0-15) to be enabled

~XBIOS(28,d%,reg%)

           reads and writes from and to the sound chip register

           r%       returns register value when reading
           d%       value to be writen (8 bits)
           r%       register number (0-15),  bit 7 defines write  mode
                    when set.

~XBIOS(29,b%)

           sets the bit of port A on the register of the sound chip to
           zero

           b%       bit pattern wicj is OR'ed with existing contents.

~XBIOS(30,b%)

           sets the port A bit of the sound chip register to 1

           b%       bit  pattern  which  is ANDed  with  the  existing
                    contents.

XBIOS(31,t%,c%,d%,L:adr%)

           Sets the MFP timers

           t%       number of the timer (0 to 3)
           c%       control register
           d%       data register
           adr%     address of the timer interrupt routine

~XBIOS(32,L:adr%)

           Starts a sound sequence, whic is processed in the interrupt

           adr%     address of the staorage area

r%=XBIOS(33,c%)

           sets or reads the printer parameters

           r%       current configuration when c%=1
           c%       Bit       set            reset
                    0         Dot Matrix     Daisy Wheel
                    1         Monochrome     Colour
                    2         Atari          Epson
                    3         Parallel       RS-232
                    4         Continuous     Single sheet

r%=XBIOS(34)

           returns  address of table with vectors to the keyboard  and
           MIDI processor.

           r%       returned address

r%=XBIOS(35,a%,w%)

           sets and reads keyboard repeat rate

           r%       current data
                    bits      0-7  repeat rate
                              8-15  time of repeat delay
           a%       repeat delay
           w%       repeat rate

~XBIOS(36,L:adr%)

           Hardcopy routine returns parameter block address

           adr%     address  of  a parameter block  for  the  hardcopy
                    routine.

~XBIOS(37)

           waits for next vertical blank interrupt.

~XBIOS(38,L:adr%)

           calls an assembler routine in supervisor mode

           adr%     address of assembler routine

~XBIOS(39)

           turns off AES if not in ROM

r%=XBIOS(64,b%)

           contols and interrogates the blitter

           r%       b%=-1          current blitter status
                                   bit 1 : blitter there
XOR
Syntax:    x XOR y
Action:    Logical exclusive OR operator


XOR()
Syntax:    XOR(x,y)
Action:    Sets those bits in x that are different in x and y.


_DATA
Syntax:    _DATA
           _DATA=
Action:    Specifies the position of the DATA pointer.  _DATA is 0  if
           the next READ would result in an out of data message.


~
Syntax:    ~function
Action:    Similar to VOID. Forget the returned value

End of File